From dbf32eb6ca1c0666c6826992af1d986d0e81b2c3 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Tue, 12 Apr 2011 18:58:41 -0300 Subject: [PATCH 01/59] Changed Object#either? to Object#among? on guides --- .../source/active_support_core_extensions.textile | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile index 3ba840c044..6e65771b1d 100644 --- a/railties/guides/source/active_support_core_extensions.textile +++ b/railties/guides/source/active_support_core_extensions.textile @@ -442,9 +442,9 @@ require_library_or_gem('mysql') NOTE: Defined in +active_support/core_ext/kernel/requires.rb+. -h4. +in?+ and +either?+ +h4. +in?+ and +among?+ -The predicate +in?+ tests if an object is included in another object, and the predicate +either?+ tests if an object is included in a list of objects which will be passed as arguments. +The predicate +in?+ tests if an object is included in another object, and the predicate +among?+ tests if an object is included in a list of objects which will be passed as arguments. Examples of +in?+: @@ -454,12 +454,12 @@ Examples of +in?+: 25.in?(30..50) # => false -Examples of +either?+: +Examples of +among?+: - 1.either?(1,2,3) # => true - 5.either?(1,2,3) # => false - [1,2,3].either?([1,2,3], 2, [3,4,5]) # => true + 1.among?(1,2,3) # => true + 5.among?(1,2,3) # => false + [1,2,3].among?([1,2,3], 2, [3,4,5]) # => true NOTE: Defined in +active_support/core_ext/object/inclusion.rb+. From b2cb99125138bcec3206562a1447991bb3fef63d Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Wed, 13 Apr 2011 09:59:01 -0300 Subject: [PATCH 02/59] Removed Object#among? from guides --- .../source/active_support_core_extensions.textile | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile index 6e65771b1d..4cedba1d4d 100644 --- a/railties/guides/source/active_support_core_extensions.textile +++ b/railties/guides/source/active_support_core_extensions.textile @@ -442,9 +442,9 @@ require_library_or_gem('mysql') NOTE: Defined in +active_support/core_ext/kernel/requires.rb+. -h4. +in?+ and +among?+ +h4. +in?+ -The predicate +in?+ tests if an object is included in another object, and the predicate +among?+ tests if an object is included in a list of objects which will be passed as arguments. +The predicate +in?+ tests if an object is included in another object. Examples of +in?+: @@ -454,14 +454,6 @@ Examples of +in?+: 25.in?(30..50) # => false -Examples of +among?+: - - - 1.among?(1,2,3) # => true - 5.among?(1,2,3) # => false - [1,2,3].among?([1,2,3], 2, [3,4,5]) # => true - - NOTE: Defined in +active_support/core_ext/object/inclusion.rb+. h3. Extensions to +Module+ From 21c03a2f48b4ac9acb6814aa3686bc7a6863120d Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Wed, 13 Apr 2011 15:42:44 -0300 Subject: [PATCH 03/59] Update guides with new scaffold.css path --- railties/guides/source/generators.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/railties/guides/source/generators.textile b/railties/guides/source/generators.textile index d32ba48003..44c15be7bf 100644 --- a/railties/guides/source/generators.textile +++ b/railties/guides/source/generators.textile @@ -190,7 +190,7 @@ $ rails generate scaffold User name:string invoke test_unit create test/unit/helpers/users_helper_test.rb invoke stylesheets - create public/stylesheets/scaffold.css + create app/assets/stylesheets/scaffold.css Looking at this output, it's easy to understand how generators work in Rails 3.0 and above. The scaffold generator doesn't actually generate anything, it just invokes others to do the work. This allows us to add/replace/remove any of those invocations. For instance, the scaffold generator invokes the scaffold_controller generator, which invokes erb, test_unit and helper generators. Since each generator has a single responsibility, they are easy to reuse, avoiding code duplication. From 04a75e02894e15aa3aaf92e3e856b091a2386f14 Mon Sep 17 00:00:00 2001 From: Matt Duncan Date: Wed, 13 Apr 2011 17:19:47 -0400 Subject: [PATCH 04/59] Moving note out of prologue to match other guides and so it'll display correctly --- railties/guides/source/command_line.textile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/railties/guides/source/command_line.textile b/railties/guides/source/command_line.textile index f3e8d880df..ac3a1c0404 100644 --- a/railties/guides/source/command_line.textile +++ b/railties/guides/source/command_line.textile @@ -8,10 +8,10 @@ Rails comes with every command line tool you'll need to * Mess with objects through an interactive shell * Profile and benchmark your new creation -NOTE: This tutorial assumes you have basic Rails knowledge from reading the "Getting Started with Rails Guide":getting_started.html. - endprologue. +NOTE: This tutorial assumes you have basic Rails knowledge from reading the "Getting Started with Rails Guide":getting_started.html. + WARNING. This Guide is based on Rails 3.0. Some of the code shown here will not work in earlier versions of Rails. h3. Command Line Basics From f8ecb46e82154979a548d36183b25375982aca08 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Wed, 13 Apr 2011 19:54:31 -0300 Subject: [PATCH 05/59] Documented +ActiveSupport::Notifications+ module. --- railties/guides/source/initialization.textile | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/railties/guides/source/initialization.textile b/railties/guides/source/initialization.textile index 7c01f01b24..33045954ee 100644 --- a/railties/guides/source/initialization.textile +++ b/railties/guides/source/initialization.textile @@ -592,7 +592,11 @@ This file defines the behavior of the +ActiveSupport::Deprecation+ module, setti h4. +activesupport/lib/active_support/notifications.rb+ -TODO: document +ActiveSupport::Notifications+. +This file defines the +ActiveSupport::Notifications+ module. Notifications provides an instrumentation API for Ruby, shipping with a queue implementation that consumes and publish events to log subscribers in a thread. + +The "API documentation":http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html for +ActiveSupport::Notifications+ explains the usage of this module, including the methods that it defines. + +The file required in +active_support/notifications.rb+ is +active_support/core_ext/module/delegation+ which is documented in the "Active Support Core Extensions Guide":http://guides.rubyonrails.org/active_support_core_extensions.html#method-delegation. h4. +activesupport/core_ext/array/wrap+ From 1447ff56545f53101c5fddbdea5667a8ff68cd8e Mon Sep 17 00:00:00 2001 From: Matt Duncan Date: Wed, 13 Apr 2011 20:17:22 -0400 Subject: [PATCH 06/59] Making identifiers consistent in example --- railties/guides/source/caching_with_rails.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/railties/guides/source/caching_with_rails.textile b/railties/guides/source/caching_with_rails.textile index 297ba2d661..995a835ce8 100644 --- a/railties/guides/source/caching_with_rails.textile +++ b/railties/guides/source/caching_with_rails.textile @@ -322,7 +322,7 @@ You can use Hashes and Arrays of values as cache keys. # This is a legal cache key -Rails.cache.read(:site => "mysite", :owners => [owner_1, owner2]) +Rails.cache.read(:site => "mysite", :owners => [owner_1, owner_2]) The keys you use on +Rails.cache+ will not be the same as those actually used with the storage engine. They may be modified with a namespace or altered to fit technology backend constraints. This means, for instance, that you can't save values with +Rails.cache+ and then try to pull them out with the +memcache-client+ gem. However, you also don't need to worry about exceeding the memcached size limit or violating syntax rules. From e56b19bbed275bd6d2bd0574300e5f0f6b85add0 Mon Sep 17 00:00:00 2001 From: Matt Duncan Date: Wed, 13 Apr 2011 20:32:36 -0400 Subject: [PATCH 07/59] Aligning table cells --- railties/guides/source/testing.textile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/railties/guides/source/testing.textile b/railties/guides/source/testing.textile index 2809c6d076..3b4cb3d8a5 100644 --- a/railties/guides/source/testing.textile +++ b/railties/guides/source/testing.textile @@ -415,8 +415,8 @@ NOTE: +assert_valid(record)+ has been deprecated. Please use +assert(record.vali |_.Assertion |_.Purpose| |+assert_valid(record)+ |Ensures that the passed record is valid by Active Record standards and returns any error messages if it is not.| -|+assert_difference(expressions, difference = 1, message = nil) {...}+ |Test numeric difference between the return value of an expression as a result of what is evaluated in the yielded block.| -|+assert_no_difference(expressions, message = nil, &block)+ |Asserts that the numeric result of evaluating an expression is not changed before and after invoking the passed in block.| +|+assert_difference(expressions, difference = 1, message = nil) {...}+ |Test numeric difference between the return value of an expression as a result of what is evaluated in the yielded block.| +|+assert_no_difference(expressions, message = nil, &block)+ |Asserts that the numeric result of evaluating an expression is not changed before and after invoking the passed in block.| |+assert_recognizes(expected_options, path, extras={}, message=nil)+ |Asserts that the routing of the given path was handled correctly and that the parsed options (given in the expected_options hash) match path. Basically, it asserts that Rails recognizes the route given by expected_options.| |+assert_generates(expected_path, options, defaults={}, extras = {}, message=nil)+ |Asserts that the provided options can be used to generate the provided path. This is the inverse of assert_recognizes. The extras parameter is used to tell the request the names and values of additional request parameters that would be in a query string. The message parameter allows you to specify a custom error message for assertion failures.| |+assert_response(type, message = nil)+ |Asserts that the response comes with a specific status code. You can specify +:success+ to indicate 200, +:redirect+ to indicate 300-399, +:missing+ to indicate 404, or +:error+ to match the 500-599 range| From 974a6aa176ff5549e00f1a126ba5d46fa175c59e Mon Sep 17 00:00:00 2001 From: Matt Duncan Date: Wed, 13 Apr 2011 20:49:14 -0400 Subject: [PATCH 08/59] Remove trailing whitespace --- railties/guides/source/initialization.textile | 12 +++---- railties/guides/source/plugins.textile | 34 +++++++++---------- .../ruby_on_rails_guides_guidelines.textile | 2 +- 3 files changed, 24 insertions(+), 24 deletions(-) diff --git a/railties/guides/source/initialization.textile b/railties/guides/source/initialization.textile index 33045954ee..013eca2a35 100644 --- a/railties/guides/source/initialization.textile +++ b/railties/guides/source/initialization.textile @@ -468,7 +468,7 @@ h4. +config/application.rb+ This file requires +config/boot.rb+, but only if it hasn't been required before, which would be the case in +rails server+ but *wouldn't* be the case with Passenger. -Then the fun begins! +Then the fun begins! h3. Loading Rails @@ -664,7 +664,7 @@ The +active_support/inflector/methods+ file has already been required by +active h4. +activesupport/lib/active_support/inflector/inflections.rb+ -This file references the +ActiveSupport::Inflector+ constant which isn't loaded by this point. But there were autoloads set up in +activesupport/lib/active_support.rb+ which will load the file which loads this constant and so then it will be defined. Then this file defines pluralization and singularization rules for words in Rails. This is how Rails knows how to pluralize "tomato" to "tomatoes". +This file references the +ActiveSupport::Inflector+ constant which isn't loaded by this point. But there were autoloads set up in +activesupport/lib/active_support.rb+ which will load the file which loads this constant and so then it will be defined. Then this file defines pluralization and singularization rules for words in Rails. This is how Rails knows how to pluralize "tomato" to "tomatoes". h4. +activesupport/lib/active_support/inflector/transliterate.rb+ @@ -698,7 +698,7 @@ h4. Back to +railties/lib/rails/plugin.rb+ The next file required in this is a core extension from Active Support called +array/conversions+ which is covered in "this section":http://guides.rubyonrails.org/active_support_core_extensions.html#array-conversions of the Active Support Core Extensions Guide. -Once that file has finished loading, the +Rails::Plugin+ class is defined. +Once that file has finished loading, the +Rails::Plugin+ class is defined. h4. Back to +railties/lib/rails/application.rb+ @@ -708,7 +708,7 @@ Once this file's done then we go back to the +railties/lib/rails.rb+ file, which h4. +railties/lib/rails/version.rb+ -Much like +active_support/version+, this file defines the +VERSION+ constant which has a +STRING+ constant on it which returns the current version of Rails. +Much like +active_support/version+, this file defines the +VERSION+ constant which has a +STRING+ constant on it which returns the current version of Rails. Once this file has finished loading we go back to +railties/lib/rails.rb+ which then requires +active_support/railtie.rb+. @@ -926,7 +926,7 @@ This file defines the +ActionDispatch::Railtie+ class, but not before requiring h4. +activesupport/lib/action_dispatch.rb+ -This file attempts to locate the +active_support+ and +active_model+ libraries by looking a couple of directories back from the current file and then adds the +active_support+ and +active_model+ +lib+ directories to the load path, but only if they aren't already, which they are. +This file attempts to locate the +active_support+ and +active_model+ libraries by looking a couple of directories back from the current file and then adds the +active_support+ and +active_model+ +lib+ directories to the load path, but only if they aren't already, which they are. activesupport_path = File.expand_path('../../../activesupport/lib', __FILE__) @@ -1112,4 +1112,4 @@ However the require after these is to a file that hasn't yet been loaded, +actio h4. +actionpack/lib/action_view.rb+ -+action_view.rb+ ++action_view.rb+ diff --git a/railties/guides/source/plugins.textile b/railties/guides/source/plugins.textile index 2d9821e627..31158d8742 100644 --- a/railties/guides/source/plugins.textile +++ b/railties/guides/source/plugins.textile @@ -17,8 +17,8 @@ This guide describes how to build a test-driven plugin that will: * Add methods to ActiveRecord::Base in the tradition of the 'acts_as' plugins * Give you information about where to put generators in your plugin. -For the purpose of this guide pretend for a moment that you are an avid bird watcher. -Your favorite bird is the Yaffle, and you want to create a plugin that allows other developers to share in the Yaffle +For the purpose of this guide pretend for a moment that you are an avid bird watcher. +Your favorite bird is the Yaffle, and you want to create a plugin that allows other developers to share in the Yaffle goodness. endprologue. @@ -27,21 +27,21 @@ h3. Setup h4. Generating the Plugin Skeleton -Rails currently ships with a generator to generate a plugin within a Rails application. Help text is available that will explain +Rails currently ships with a generator to generate a plugin within a Rails application. Help text is available that will explain how this generator works. $ rails generate plugin --help -This generator places the plugin into the vendor/plugins directory. +This generator places the plugin into the vendor/plugins directory. -Vendored plugins are useful for quickly prototyping your plugin but current thinking in the Rails community is shifting towards +Vendored plugins are useful for quickly prototyping your plugin but current thinking in the Rails community is shifting towards packaging plugins as gems, especially with the inclusion of Bundler as the Rails dependency manager. Packaging a plugin as a gem may be overkill for any plugins that will not be shared across projects but doing so from the start makes it easier to share the plugin going forward without adding too much additional overhead during development. Rails 3.1 will ship with a plugin generator that will default to setting up a plugin -as a gem. This tutorial will begin to bridge that gap by demonstrating how to create a gem based plugin using the +as a gem. This tutorial will begin to bridge that gap by demonstrating how to create a gem based plugin using the "Enginex gem":http://www.github.com/josevalim/enginex. @@ -133,7 +133,7 @@ $ rails console h3. Add an "acts_as" Method to Active Record -A common pattern in plugins is to add a method called 'acts_as_something' to models. In this case, you +A common pattern in plugins is to add a method called 'acts_as_something' to models. In this case, you want to write a method called 'acts_as_yaffle' that adds a 'squawk' method to your Active Record models. To begin, set up your files so that you have: @@ -169,8 +169,8 @@ end h4. Add a Class Method -This plugin will expect that you've added a method to your model named 'last_squawk'. However, the -plugin users might have already defined a method on their model named 'last_squawk' that they use +This plugin will expect that you've added a method to your model named 'last_squawk'. However, the +plugin users might have already defined a method on their model named 'last_squawk' that they use for something else. This plugin will allow the name to be changed by adding a class method called 'yaffle_text_field'. To start out, write a failing test that shows the behavior you'd like: @@ -210,7 +210,7 @@ When you run +rake+, you should see the following: This tells us that we don't have the necessary models (Hickwall and Wickwall) that we are trying to test. -We can easily generate these models in our "dummy" Rails application by running the following commands from the +We can easily generate these models in our "dummy" Rails application by running the following commands from the test/dummy directory: @@ -220,7 +220,7 @@ $ rails generate model Wickwall last_squak:string last_tweet:string Now you can create the necessary database tables in your testing database by navigating to your dummy app -and migrating the database. First +and migrating the database. First $ cd test/dummy @@ -319,7 +319,7 @@ When you run +rake+ you should see the tests all pass: h4. Add an Instance Method -This plugin will add a method named 'squawk' to any Active Record objects that call 'acts_as_yaffle'. The 'squawk' +This plugin will add a method named 'squawk' to any Active Record objects that call 'acts_as_yaffle'. The 'squawk' method will simply set the value of one of the fields in the database. To start out, write a failing test that shows the behavior you'd like: @@ -352,7 +352,7 @@ class ActsAsYaffleTest < Test::Unit::TestCase end -Run the test to make sure the last two tests fail the an error that contains "NoMethodError: undefined method `squawk'", +Run the test to make sure the last two tests fail the an error that contains "NoMethodError: undefined method `squawk'", then update 'acts_as_yaffle.rb' to look like this: @@ -387,8 +387,8 @@ Run +rake+ one final time and you should see: 7 tests, 7 assertions, 0 failures, 0 errors, 0 skips -NOTE: The use of +write_attribute+ to write to the field in model is just one example of how a plugin can -interact with the model, and will not always be the right method to use. For example, you could also +NOTE: The use of +write_attribute+ to write to the field in model is just one example of how a plugin can +interact with the model, and will not always be the right method to use. For example, you could also use +send("#{self.class.yaffle_text_field}=", string.to_squawk)+. h3. Generators @@ -398,7 +398,7 @@ the creation of generators can be found in the "Generators Guide":generators.htm h3. Publishing your Gem -Gem plugins in progress can be easily be shared from any Git repository. To share the Yaffle gem with others, simply +Gem plugins in progress can be easily be shared from any Git repository. To share the Yaffle gem with others, simply commit the code to a Git repository (like Github) and add a line to the Gemfile of the any application: @@ -423,7 +423,7 @@ Move the directory that you created for the gem based plugin into the vendor/plu require 'yaffle' -You can test this by changing to the Rails application that you added the plugin to and starting a rails console. Once in the +You can test this by changing to the Rails application that you added the plugin to and starting a rails console. Once in the console we can check to see if the String has an instance method of to_squawk. $ cd my_app diff --git a/railties/guides/source/ruby_on_rails_guides_guidelines.textile b/railties/guides/source/ruby_on_rails_guides_guidelines.textile index 8e55780dca..26a5a4c3c9 100644 --- a/railties/guides/source/ruby_on_rails_guides_guidelines.textile +++ b/railties/guides/source/ruby_on_rails_guides_guidelines.textile @@ -13,7 +13,7 @@ h3. Prologue Each guide should start with motivational text at the top (that's the little introduction in the blue area.) The prologue should tell the reader what the guide is about, and what they will learn. See for example the "Routing Guide":routing.html. h3. Titles - + The title of every guide uses +h2+, guide sections use +h3+, subsections +h4+, etc. Capitalize all words except for internal articles, prepositions, conjunctions, and forms of the verb to be: From 2f242652374d40726a5076a531a667e4482744df Mon Sep 17 00:00:00 2001 From: Matt Duncan Date: Wed, 13 Apr 2011 20:58:26 -0400 Subject: [PATCH 09/59] Making colon usage consistent --- .../source/active_record_querying.textile | 2 +- .../rails_application_templates.textile | 44 +++++++++---------- 2 files changed, 23 insertions(+), 23 deletions(-) diff --git a/railties/guides/source/active_record_querying.textile b/railties/guides/source/active_record_querying.textile index df8e35ed33..b970c55327 100644 --- a/railties/guides/source/active_record_querying.textile +++ b/railties/guides/source/active_record_querying.textile @@ -993,7 +993,7 @@ Client.count # SELECT count(*) AS count_all FROM clients -Or on a relation : +Or on a relation: Client.where(:first_name => 'Ryan').count diff --git a/railties/guides/source/rails_application_templates.textile b/railties/guides/source/rails_application_templates.textile index 8e51f9e23b..388d8eea3e 100644 --- a/railties/guides/source/rails_application_templates.textile +++ b/railties/guides/source/rails_application_templates.textile @@ -11,19 +11,19 @@ endprologue. h3. Usage -To apply a template, you need to provide the Rails generator with the location of the template you wish to apply, using -m option : +To apply a template, you need to provide the Rails generator with the location of the template you wish to apply, using -m option: $ rails new blog -m ~/template.rb -It's also possible to apply a template using a URL : +It's also possible to apply a template using a URL: $ rails new blog -m https://gist.github.com/755496.txt -Alternatively, you can use the rake task +rails:template+ to apply a template to an existing Rails application : +Alternatively, you can use the rake task +rails:template+ to apply a template to an existing Rails application: $ rake rails:template LOCATION=~/template.rb @@ -31,7 +31,7 @@ $ rake rails:template LOCATION=~/template.rb h3. Template API -Rails templates API is very self explanatory and easy to understand. Here's an example of a typical Rails template : +Rails templates API is very self explanatory and easy to understand. Here's an example of a typical Rails template: # template.rb @@ -45,20 +45,20 @@ git :add => "." git :commit => "-a -m 'Initial commit'" -The following sections outlines the primary methods provided by the API : +The following sections outlines the primary methods provided by the API: h4. gem(name, options = {}) Adds a +gem+ entry for the supplied gem to the generated application’s +Gemfile+. -For example, if your application depends on the gems +bj+ and +nokogiri+ : +For example, if your application depends on the gems +bj+ and +nokogiri+: gem "bj" gem "nokogiri" -Please note that this will NOT install the gems for you. So you may want to run the +rake gems:install+ task too : +Please note that this will NOT install the gems for you. So you may want to run the +rake gems:install+ task too: rake "gems:install" @@ -80,13 +80,13 @@ h4. plugin(name, options = {}) Installs a plugin to the generated application. -Plugin can be installed from Git : +Plugin can be installed from Git: plugin 'authentication', :git => 'git://github.com/foor/bar.git' -You can even install plugins as git submodules : +You can even install plugins as git submodules: plugin 'authentication', :git => 'git://github.com/foor/bar.git', @@ -95,7 +95,7 @@ plugin 'authentication', :git => 'git://github.com/foor/bar.git', Please note that you need to +git :init+ before you can install a plugin as a submodule. -Or use plain old SVN : +Or use plain old SVN: plugin 'usingsvn', :svn => 'svn://example.com/usingsvn/trunk' @@ -105,7 +105,7 @@ h4. vendor/lib/file/initializer(filename, data = nil, &block) Adds an initializer to the generated application’s +config/initializers+ directory. -Lets say you like using +Object#not_nil?+ and +Object#not_blank?+ : +Lets say you like using +Object#not_nil?+ and +Object#not_blank?+: initializer 'bloatlol.rb', <<-CODE @@ -123,7 +123,7 @@ CODE Similarly +lib()+ creates a file in the +lib/+ directory and +vendor()+ creates a file in the +vendor/+ directory. -There is even +file()+, which accepts a relative path from +Rails.root+ and creates all the directories/file needed : +There is even +file()+, which accepts a relative path from +Rails.root+ and creates all the directories/file needed: file 'app/components/foo.rb', <<-CODE @@ -136,7 +136,7 @@ That’ll create +app/components+ directory and put +foo.rb+ in there. h4. rakefile(filename, data = nil, &block) -Creates a new rake file under +lib/tasks+ with the supplied tasks : +Creates a new rake file under +lib/tasks+ with the supplied tasks: rakefile("bootstrap.rake") do @@ -154,7 +154,7 @@ The above creates +lib/tasks/bootstrap.rake+ with a +boot:strap+ rake task. h4. generate(what, args) -Runs the supplied rails generator with given arguments. For example, I love to scaffold some whenever I’m playing with Rails : +Runs the supplied rails generator with given arguments. For example, I love to scaffold some whenever I’m playing with Rails: generate(:scaffold, "person", "name:string", "address:text", "age:number") @@ -162,7 +162,7 @@ generate(:scaffold, "person", "name:string", "address:text", "age:number") h4. run(command) -Executes an arbitrary command. Just like the backticks. Let's say you want to remove the +public/index.html+ file : +Executes an arbitrary command. Just like the backticks. Let's say you want to remove the +public/index.html+ file: run "rm public/index.html" @@ -170,19 +170,19 @@ run "rm public/index.html" h4. rake(command, options = {}) -Runs the supplied rake tasks in the Rails application. Let's say you want to migrate the database : +Runs the supplied rake tasks in the Rails application. Let's say you want to migrate the database: rake "db:migrate" -You can also run rake tasks with a different Rails environment : +You can also run rake tasks with a different Rails environment: rake "db:migrate", :env => 'production' -Or even use sudo : +Or even use sudo: rake "gems:install", :sudo => true @@ -190,7 +190,7 @@ rake "gems:install", :sudo => true h4. route(routing_code) -This adds a routing entry to the +config/routes.rb+ file. In above steps, we generated a person scaffold and also removed +public/index.html+. Now to make +PeopleController#index+ as the default page for the application : +This adds a routing entry to the +config/routes.rb+ file. In above steps, we generated a person scaffold and also removed +public/index.html+. Now to make +PeopleController#index+ as the default page for the application: route "root :to => 'person#index'" @@ -208,7 +208,7 @@ end h4. ask(question) -+ask()+ gives you a chance to get some feedback from the user and use it in your templates. Lets say you want your user to name the new shiny library you’re adding : ++ask()+ gives you a chance to get some feedback from the user and use it in your templates. Lets say you want your user to name the new shiny library you’re adding: lib_name = ask("What do you want to call the shiny library ?") @@ -222,7 +222,7 @@ CODE h4. yes?(question) or no?(question) -These methods let you ask questions from templates and decide the flow based on the user’s answer. Lets say you want to freeze rails only if the user want to : +These methods let you ask questions from templates and decide the flow based on the user’s answer. Lets say you want to freeze rails only if the user want to: rake("rails:freeze:gems") if yes?("Freeze rails gems ?") @@ -231,7 +231,7 @@ no?(question) acts just the opposite. h4. git(:must => "-a love") -Rails templates let you run any git command : +Rails templates let you run any git command: git :init From beed866e4335e8418ced59e293b6a71d12214f4f Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Wed, 13 Apr 2011 23:38:05 -0300 Subject: [PATCH 10/59] Fix patch file name to make it consistent with the rest of the guide --- railties/guides/source/contributing_to_ruby_on_rails.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/railties/guides/source/contributing_to_ruby_on_rails.textile b/railties/guides/source/contributing_to_ruby_on_rails.textile index 1fcc4fd7e3..9ac8d11c07 100644 --- a/railties/guides/source/contributing_to_ruby_on_rails.textile +++ b/railties/guides/source/contributing_to_ruby_on_rails.textile @@ -361,7 +361,7 @@ $ git apply --check my_new_patch.diff Please make sure the patch does not introduce whitespace errors: -$ git apply --whitespace=error-all mynew_patch.diff +$ git apply --whitespace=error-all my_new_patch.diff From 02883a1090e327b115c12c3f1dc97f1474ef3c9f Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Thu, 14 Apr 2011 09:36:22 -0300 Subject: [PATCH 11/59] Update Contributing to the Rails Code guide for automatically change the status of LH tickets --- .../source/contributing_to_ruby_on_rails.textile | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/railties/guides/source/contributing_to_ruby_on_rails.textile b/railties/guides/source/contributing_to_ruby_on_rails.textile index 9ac8d11c07..ded67f0e4f 100644 --- a/railties/guides/source/contributing_to_ruby_on_rails.textile +++ b/railties/guides/source/contributing_to_ruby_on_rails.textile @@ -314,14 +314,20 @@ You should not be the only person who looks at the code before you submit it. Yo You might also want to check out the "RailsBridge BugMash":http://wiki.railsbridge.org/projects/railsbridge/wiki/BugMash as a way to get involved in a group effort to improve Rails. This can help you get started and help check your code when you're writing your first patches. +h4. Create a Lighthouse Ticket + +Now create a ticket for your patch. Go to the "new ticket":http://rails.lighthouseapp.com/projects/8994-ruby-on-rails/tickets/new page at Lighthouse. Fill in a reasonable title and description, as well as tag the ticket with the ‘patch’ tag and whatever other subject area tags make sense. Write down your ticket number, for you will need it in the following step. + h4. Commit Your Changes When you're happy with the code on your computer, you need to commit the changes to git: -$ git commit -a -m "Here is a commit message" +$ git commit -a -m "[#ticket_number state:committed] Here is a commit message" +NOTE: By adding '[#ticket_number state:committed]' on your commit message, the ticket will automatically change its status to commited once your patch is pushed to the repository. + h4. Update master It’s pretty likely that other changes to master have happened while you were working. Go get them: @@ -364,10 +370,9 @@ Please make sure the patch does not introduce whitespace errors: $ git apply --whitespace=error-all my_new_patch.diff +h4. Attach your Patch to the Lighthouse Ticket -h4. Create a Lighthouse Ticket - -Now create a ticket with your patch. Go to the "new ticket":http://rails.lighthouseapp.com/projects/8994-ruby-on-rails/tickets/new page at Lighthouse. Fill in a reasonable title and description, remember to attach your patch file, and tag the ticket with the ‘patch’ tag and whatever other subject area tags make sense. +Now you need to update the ticket by attaching the patch file you just created. h4. Get Some Feedback @@ -385,6 +390,7 @@ All contributions, either via master or docrails, get credit in "Rails Contribut h3. Changelog +* April 14, 2001: Modified Contributing to the Rails Code section to add '[#ticket_number state:commited]' on patches commit messages by "Sebastian Martinez":http://wyeworks.com * December 28, 2010: Complete revision by "Xavier Noria":credits.html#fxn * April 6, 2010: Fixed document to validate XHTML 1.0 Strict. "Jaime Iniesta":http://jaimeiniesta.com * August 1, 2009: Updates/amplifications by "Mike Gunderloy":credits.html#mgunderloy From 9aff7e0898cd9f84fdbd961d895440523c100c82 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Thu, 14 Apr 2011 10:04:10 -0300 Subject: [PATCH 12/59] Update guides with controller generator producing asset stubs --- railties/guides/source/command_line.textile | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/railties/guides/source/command_line.textile b/railties/guides/source/command_line.textile index ac3a1c0404..7b2ab92ccc 100644 --- a/railties/guides/source/command_line.textile +++ b/railties/guides/source/command_line.textile @@ -144,10 +144,13 @@ $ rails generate controller Greetings hello create app/helpers/greetings_helper.rb invoke test_unit create test/unit/helpers/greetings_helper_test.rb + invoke assets + create app/assets/javascripts/greetings.js + create app/assets/stylesheets/greetings.css -What all did this generate? It made sure a bunch of directories were in our application, and created a controller file, a functional test file, a helper for the view, and a view file. +What all did this generate? It made sure a bunch of directories were in our application, and created a controller file, a view file, a functional test file, a helper for the view, a javascript file and a stylesheet file. Check out the controller and modify it a little (in +app/controllers/greetings_controller.rb+): From 1bcc7055d840b39d1cc7fff934a62be5ea3c9539 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Thu, 14 Apr 2011 10:05:08 -0300 Subject: [PATCH 13/59] Remove extra whitespace --- railties/guides/source/command_line.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/railties/guides/source/command_line.textile b/railties/guides/source/command_line.textile index 7b2ab92ccc..a46087c91b 100644 --- a/railties/guides/source/command_line.textile +++ b/railties/guides/source/command_line.textile @@ -150,7 +150,7 @@ $ rails generate controller Greetings hello -What all did this generate? It made sure a bunch of directories were in our application, and created a controller file, a view file, a functional test file, a helper for the view, a javascript file and a stylesheet file. +What all did this generate? It made sure a bunch of directories were in our application, and created a controller file, a view file, a functional test file, a helper for the view, a javascript file and a stylesheet file. Check out the controller and modify it a little (in +app/controllers/greetings_controller.rb+): From 28bf4c67cab5cf266eeccb79bd543202daea3578 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Thu, 14 Apr 2011 10:59:48 -0300 Subject: [PATCH 14/59] Move [#ticket_number state:commited] to the end of the commit message --- railties/guides/source/contributing_to_ruby_on_rails.textile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/railties/guides/source/contributing_to_ruby_on_rails.textile b/railties/guides/source/contributing_to_ruby_on_rails.textile index ded67f0e4f..cbc4acfeca 100644 --- a/railties/guides/source/contributing_to_ruby_on_rails.textile +++ b/railties/guides/source/contributing_to_ruby_on_rails.textile @@ -323,10 +323,10 @@ h4. Commit Your Changes When you're happy with the code on your computer, you need to commit the changes to git: -$ git commit -a -m "[#ticket_number state:committed] Here is a commit message" +$ git commit -a -m "Here is a commit message [#ticket_number state:committed]" -NOTE: By adding '[#ticket_number state:committed]' on your commit message, the ticket will automatically change its status to commited once your patch is pushed to the repository. +NOTE: By adding '[#ticket_number state:committed]' at the end of your commit message, the ticket will automatically change its status to commited once your patch is pushed to the repository. h4. Update master From 5be72684f6bbaf83359864b3f46c156de1d9e3ba Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Thu, 14 Apr 2011 13:45:00 -0300 Subject: [PATCH 15/59] Update guide mentioning that +in?+ may raise an +ArgumentError+ exception --- railties/guides/source/active_support_core_extensions.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile index 4cedba1d4d..b7f842a0d0 100644 --- a/railties/guides/source/active_support_core_extensions.textile +++ b/railties/guides/source/active_support_core_extensions.textile @@ -444,7 +444,7 @@ NOTE: Defined in +active_support/core_ext/kernel/requires.rb+. h4. +in?+ -The predicate +in?+ tests if an object is included in another object. +The predicate +in?+ tests if an object is included in another object. An +ArgumentError+ exception will be raised if the argument passed does not respond to +include?+. Examples of +in?+: From bbfc6cda82b9550bfc955ecf66c0b803e3002e0a Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Thu, 14 Apr 2011 20:37:12 -0300 Subject: [PATCH 16/59] Remove extra whitespaces from guides --- .../source/action_controller_overview.textile | 2 +- .../source/action_view_overview.textile | 6 ++-- .../source/active_record_querying.textile | 4 +-- railties/guides/source/ajax_on_rails.textile | 8 ++--- .../guides/source/caching_with_rails.textile | 10 +++--- railties/guides/source/form_helpers.textile | 6 ++-- railties/guides/source/generators.textile | 2 +- .../guides/source/getting_started.textile | 32 +++++++++---------- railties/guides/source/i18n.textile | 4 +-- railties/guides/source/initialization.textile | 2 +- .../source/layouts_and_rendering.textile | 8 ++--- railties/guides/source/migrations.textile | 4 +-- railties/guides/source/plugins.textile | 28 ++++++++-------- railties/guides/source/routing.textile | 4 +-- railties/guides/source/security.textile | 10 +++--- 15 files changed, 65 insertions(+), 65 deletions(-) diff --git a/railties/guides/source/action_controller_overview.textile b/railties/guides/source/action_controller_overview.textile index 496dc7224b..f8b586c151 100644 --- a/railties/guides/source/action_controller_overview.textile +++ b/railties/guides/source/action_controller_overview.textile @@ -368,7 +368,7 @@ class UsersController < ApplicationController respond_to do |format| format.html # index.html.erb format.xml { render :xml => @users} - format.json { render :json => @users} + format.json { render :json => @users} end end end diff --git a/railties/guides/source/action_view_overview.textile b/railties/guides/source/action_view_overview.textile index d0b3ee6bfc..1a81920249 100644 --- a/railties/guides/source/action_view_overview.textile +++ b/railties/guides/source/action_view_overview.textile @@ -262,9 +262,9 @@ Register one or more stylesheet files to be included when symbol is passed to +s ActionView::Helpers::AssetTagHelper.register_stylesheet_expansion :monkey => ["head", "body", "tail"] stylesheet_link_tag :monkey # => - - - + + + h5. auto_discovery_link_tag diff --git a/railties/guides/source/active_record_querying.textile b/railties/guides/source/active_record_querying.textile index b970c55327..7cdffe4c2e 100644 --- a/railties/guides/source/active_record_querying.textile +++ b/railties/guides/source/active_record_querying.textile @@ -546,7 +546,7 @@ Active Record provides two locking mechanisms: h4. Optimistic Locking -Optimistic locking allows multiple users to access the same record for edits, and assumes a minimum of conflicts with the data. It does this by checking whether another process has made changes to a record since it was opened. An +ActiveRecord::StaleObjectError+ exception is thrown if that has occurred and the update is ignored. +Optimistic locking allows multiple users to access the same record for edits, and assumes a minimum of conflicts with the data. It does this by checking whether another process has made changes to a record since it was opened. An +ActiveRecord::StaleObjectError+ exception is thrown if that has occurred and the update is ignored. Optimistic locking column @@ -1060,7 +1060,7 @@ If you want to find the sum of a field for all records in your table you can cal Client.sum("orders_count") -For options, please see the parent section, "Calculations":#calculations. +For options, please see the parent section, "Calculations":#calculations. h3. Changelog diff --git a/railties/guides/source/ajax_on_rails.textile b/railties/guides/source/ajax_on_rails.textile index b80df4aa58..25c1e01b55 100644 --- a/railties/guides/source/ajax_on_rails.textile +++ b/railties/guides/source/ajax_on_rails.textile @@ -42,7 +42,7 @@ You are ready to add some AJAX love to your Rails app! h4. The Quintessential AJAX Rails Helper: link_to_remote -Let's start with what is probably the most often used helper: +link_to_remote+. It has an interesting feature from the documentation point of view: the options supplied to +link_to_remote+ are shared by all other AJAX helpers, so learning the mechanics and options of +link_to_remote+ is a great help when using other helpers. +Let's start with what is probably the most often used helper: +link_to_remote+. It has an interesting feature from the documentation point of view: the options supplied to +link_to_remote+ are shared by all other AJAX helpers, so learning the mechanics and options of +link_to_remote+ is a great help when using other helpers. The signature of +link_to_remote+ function is the same as that of the standard +link_to+ helper: @@ -72,7 +72,7 @@ link_to_remote "Add to cart", If the server returns 200, the output of the above example is equivalent to our first, simple one. However, in case of error, the element with the DOM id +error+ is updated rather than the +cart+ element. -** *position* By default (i.e. when not specifying this option, like in the examples before) the repsonse is injected into the element with the specified DOM id, replacing the original content of the element (if there was any). You might want to alter this behavior by keeping the original content - the only question is where to place the new content? This can specified by the +position+ parameter, with four possibilities: +** *position* By default (i.e. when not specifying this option, like in the examples before) the repsonse is injected into the element with the specified DOM id, replacing the original content of the element (if there was any). You might want to alter this behavior by keeping the original content - the only question is where to place the new content? This can specified by the +position+ parameter, with four possibilities: *** +:before+ Inserts the response text just before the target element. More precisely, it creates a text node from the response and inserts it as the left sibling of the target element. *** +:after+ Similar behavior to +:before+, but in this case the response is inserted after the target element. *** +:top+ Inserts the text into the target element, before it's original content. If the target element was empty, this is equivalent with not specifying +:position+ at all. @@ -210,7 +210,7 @@ def javascript_test end -The above code snippet does exactly the same as the one in the previous section - going about it much more elegantly though. You don't need to worry about headers,write ugly JavaScript code into a string etc. When the first parameter to +render+ is +:update+, Rails expects a block with a single parameter (+page+ in our case, which is the traditional naming convention) which is an instance of the JavaScriptGenerator:"http://api.rubyonrails.org/classes/ActionView/Helpers/PrototypeHelper/JavaScriptGenerator/GeneratorMethods.html" object. As it's name suggests, JavaScriptGenerator is responsible for generating JavaScript from your Ruby code. You can execute multiple method calls on the +page+ instance - it's all turned into JavaScript code and sent to the server with the appropriate Content Type, "text/javascript". +The above code snippet does exactly the same as the one in the previous section - going about it much more elegantly though. You don't need to worry about headers,write ugly JavaScript code into a string etc. When the first parameter to +render+ is +:update+, Rails expects a block with a single parameter (+page+ in our case, which is the traditional naming convention) which is an instance of the JavaScriptGenerator:"http://api.rubyonrails.org/classes/ActionView/Helpers/PrototypeHelper/JavaScriptGenerator/GeneratorMethods.html" object. As it's name suggests, JavaScriptGenerator is responsible for generating JavaScript from your Ruby code. You can execute multiple method calls on the +page+ instance - it's all turned into JavaScript code and sent to the server with the appropriate Content Type, "text/javascript". h4. RJS Templates @@ -307,7 +307,7 @@ So +<<+ is used to execute an arbitrary JavaScript statement, passed as string t page.call :alert, '1+1 equals ' + result -+assign+ simply assigns a value to a variable. +call+ is similar to +<<+ with a slightly different syntax: the first parameter is the name of the function to call, followed by the list of parameters passed to the function. ++assign+ simply assigns a value to a variable. +call+ is similar to +<<+ with a slightly different syntax: the first parameter is the name of the function to call, followed by the list of parameters passed to the function. h6. Class Proxies diff --git a/railties/guides/source/caching_with_rails.textile b/railties/guides/source/caching_with_rails.textile index 995a835ce8..799339e674 100644 --- a/railties/guides/source/caching_with_rails.textile +++ b/railties/guides/source/caching_with_rails.textile @@ -25,7 +25,7 @@ h4. Page Caching Page caching is a Rails mechanism which allows the request for a generated page to be fulfilled by the webserver (i.e. apache or nginx), without ever having to go through the Rails stack at all. Obviously, this is super-fast. Unfortunately, it can't be applied to every situation (such as pages that need authentication) and since the webserver is literally just serving a file from the filesystem, cache expiration is an issue that needs to be dealt with. -So, how do you enable this super-fast cache behavior? Simple, let's say you have a controller called +ProductsController+ and an +index+ action that lists all the products +So, how do you enable this super-fast cache behavior? Simple, let's say you have a controller called +ProductsController+ and an +index+ action that lists all the products class ProductsController < ActionController @@ -152,7 +152,7 @@ expire_fragment('all_available_products') h4. Sweepers -Cache sweeping is a mechanism which allows you to get around having a ton of +expire_{page,action,fragment}+ calls in your code. It does this by moving all the work required to expire cached content into an +ActionController::Caching::Sweeper+ subclass. This class is an observer and looks for changes to an object via callbacks, and when a change occurs it expires the caches associated with that object in an around or after filter. +Cache sweeping is a mechanism which allows you to get around having a ton of +expire_{page,action,fragment}+ calls in your code. It does this by moving all the work required to expire cached content into an +ActionController::Caching::Sweeper+ subclass. This class is an observer and looks for changes to an object via callbacks, and when a change occurs it expires the caches associated with that object in an around or after filter. Continuing with our Product controller example, we could rewrite it with a sweeper like this: @@ -230,9 +230,9 @@ class ProductsController < ActionController end -The second time the same query is run against the database, it's not actually going to hit the database. The first time the result is returned from the query it is stored in the query cache (in memory) and the second time it's pulled from memory. +The second time the same query is run against the database, it's not actually going to hit the database. The first time the result is returned from the query it is stored in the query cache (in memory) and the second time it's pulled from memory. -However, it's important to note that query caches are created at the start of an action and destroyed at the end of that action and thus persist only for the duration of the action. If you'd like to store query results in a more persistent fashion, you can in Rails by using low level caching. +However, it's important to note that query caches are created at the start of an action and destroyed at the end of that action and thus persist only for the duration of the action. If you'd like to store query results in a more persistent fashion, you can in Rails by using low level caching. h3. Cache Stores @@ -352,7 +352,7 @@ class ProductsController < ApplicationController # If the request is fresh (i.e. it's not modified) then you don't need to do # anything. The default render checks for this using the parameters # used in the previous call to stale? and will automatically send a - # :not_modified. So that's it, you're done. + # :not_modified. So that's it, you're done. end diff --git a/railties/guides/source/form_helpers.textile b/railties/guides/source/form_helpers.textile index 1f21c27ae6..a63245acec 100644 --- a/railties/guides/source/form_helpers.textile +++ b/railties/guides/source/form_helpers.textile @@ -258,7 +258,7 @@ The name passed to +form_for+ controls the key used in +params+ to access the fo The helper methods called on the form builder are identical to the model object helpers except that it is not necessary to specify which object is being edited since this is already managed by the form builder. -You can create a similar binding without actually creating +<form>+ tags with the +fields_for+ helper. This is useful for editing additional model objects with the same form. For example if you had a Person model with an associated ContactDetail model you could create a form for creating both like so: +You can create a similar binding without actually creating +<form>+ tags with the +fields_for+ helper. This is useful for editing additional model objects with the same form. For example if you had a Person model with an associated ContactDetail model you could create a form for creating both like so: <%= form_for @person, :url => { :action => "create" } do |person_form| %> @@ -438,7 +438,7 @@ As with other helpers, if you were to use the +select+ helper on a form builder <%= f.select(:city_id, ...) %> -WARNING: If you are using +select+ (or similar helpers such as +collection_select+, +select_tag+) to set a +belongs_to+ association you must pass the name of the foreign key (in the example above +city_id+), not the name of association itself. If you specify +city+ instead of +city_id+ Active Record will raise an error along the lines of ActiveRecord::AssociationTypeMismatch: City(#17815740) expected, got String(#1138750) when you pass the +params+ hash to +Person.new+ or +update_attributes+. Another way of looking at this is that form helpers only edit attributes. You should also be aware of the potential security ramifications of allowing users to edit foreign keys directly. You may wish to consider the use of +attr_protected+ and +attr_accessible+. For further details on this, see the "Ruby On Rails Security Guide":security.html#_mass_assignment. +WARNING: If you are using +select+ (or similar helpers such as +collection_select+, +select_tag+) to set a +belongs_to+ association you must pass the name of the foreign key (in the example above +city_id+), not the name of association itself. If you specify +city+ instead of +city_id+ Active Record will raise an error along the lines of ActiveRecord::AssociationTypeMismatch: City(#17815740) expected, got String(#1138750) when you pass the +params+ hash to +Person.new+ or +update_attributes+. Another way of looking at this is that form helpers only edit attributes. You should also be aware of the potential security ramifications of allowing users to edit foreign keys directly. You may wish to consider the use of +attr_protected+ and +attr_accessible+. For further details on this, see the "Ruby On Rails Security Guide":security.html#_mass_assignment. h4. Option Tags from a Collection of Arbitrary Objects @@ -513,7 +513,7 @@ The +:prefix+ option is the key used to retrieve the hash of date components fro h4(#select-model-object-helpers). Model Object Helpers +select_date+ does not work well with forms that update or create Active Record objects as Active Record expects each element of the +params+ hash to correspond to one attribute. -The model object helpers for dates and times submit parameters with special names, when Active Record sees parameters with such names it knows they must be combined with the other parameters and given to a constructor appropriate to the column type. For example: +The model object helpers for dates and times submit parameters with special names, when Active Record sees parameters with such names it knows they must be combined with the other parameters and given to a constructor appropriate to the column type. For example: <%= date_select :person, :birth_date %> diff --git a/railties/guides/source/generators.textile b/railties/guides/source/generators.textile index 44c15be7bf..ac709968d9 100644 --- a/railties/guides/source/generators.textile +++ b/railties/guides/source/generators.textile @@ -383,7 +383,7 @@ if yes?("Would you like to install Devise?") end -In the above template we specify that the application relies on the +rspec-rails+ and +cucumber-rails+ gem so these two will be added to the +test+ group in the +Gemfile+. Then we pose a question to the user about whether or not they would like to install Devise. If the user replies "y" or "yes" to this question, then the template will add Devise to the +Gemfile+ outside of any group and then runs the +devise:install+ generator. This template then takes the users input and runs the +devise+ generator, with the user's answer from the last question being passed to this generator. +In the above template we specify that the application relies on the +rspec-rails+ and +cucumber-rails+ gem so these two will be added to the +test+ group in the +Gemfile+. Then we pose a question to the user about whether or not they would like to install Devise. If the user replies "y" or "yes" to this question, then the template will add Devise to the +Gemfile+ outside of any group and then runs the +devise:install+ generator. This template then takes the users input and runs the +devise+ generator, with the user's answer from the last question being passed to this generator. Imagine that this template was in a file called +template.rb+. We can use it to modify the outcome of the +rails new+ command by using the +-m+ option and passing in the filename: diff --git a/railties/guides/source/getting_started.textile b/railties/guides/source/getting_started.textile index 5906f953bf..af3525636c 100644 --- a/railties/guides/source/getting_started.textile +++ b/railties/guides/source/getting_started.textile @@ -22,7 +22,7 @@ TIP: Note that Ruby 1.8.7 p248 and p249 have marshaling bugs that crash Rails 3. * The "RubyGems":http://rubyforge.org/frs/?group_id=126 packaging system * A working installation of the "SQLite3 Database":http://www.sqlite.org -Rails is a web application framework running on the Ruby programming language. If you have no prior experience with Ruby, you will find a very steep learning curve diving straight into Rails. There are some good free resources on the internet for learning Ruby, including: +Rails is a web application framework running on the Ruby programming language. If you have no prior experience with Ruby, you will find a very steep learning curve diving straight into Rails. There are some good free resources on the internet for learning Ruby, including: * "Mr. Neighborly's Humble Little Ruby Book":http://www.humblelittlerubybook.com * "Programming Ruby":http://www.ruby-doc.org/docs/ProgrammingRuby/ @@ -78,7 +78,7 @@ Rails ships as many individual components. h5. Action Pack -Action Pack is a single gem that contains Action Controller, Action View and Action Dispatch. The "VC" part of "MVC". +Action Pack is a single gem that contains Action Controller, Action View and Action Dispatch. The "VC" part of "MVC". h5. Action Controller @@ -98,7 +98,7 @@ Action Mailer is a framework for building e-mail services. You can use Action Ma h5. Active Model -Active Model provides a defined interface between the Action Pack gem services and Object Relationship Mapping gems such as Active Record. Active Model allows Rails to utilize other ORM frameworks in place of Active Record if your application needs this. +Active Model provides a defined interface between the Action Pack gem services and Object Relationship Mapping gems such as Active Record. Active Model allows Rails to utilize other ORM frameworks in place of Active Record if your application needs this. h5. Active Record @@ -153,7 +153,7 @@ TIP. If you're working on Windows, you can quickly install Ruby and Rails with " h4. Creating the Blog Application -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. If you need to see the completed code, you can download it from "Getting Started Code":https://github.com/mikel/getting-started-code. +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. If you need to see the completed code, you can download it from "Getting Started Code":https://github.com/mikel/getting-started-code. To begin, open a terminal, navigate to a folder where you have rights to create files, and type: @@ -184,7 +184,7 @@ In any case, Rails will create a folder in your working directory called blo |doc/|In-depth documentation for your application.| |lib/|Extended modules for your application (not covered in this guide).| |log/|Application log files.| -|public/|The only folder seen to the world as-is. This is where your images, JavaScript files, stylesheets (CSS), and other static files go.| +|public/|The only folder seen to the world as-is. This is where your images, JavaScript files, stylesheets (CSS), and other static files go.| |script/|Contains the rails script that starts your app and can contain other scripts you use to deploy or run your application.| |test/|Unit tests, fixtures, and other test apparatus. These are covered in "Testing Rails Applications":testing.html| |tmp/|Temporary files| @@ -290,7 +290,7 @@ This will fire up an instance of the WEBrick web server by default (Rails can al TIP: 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. You can also click on the _About your application’s environment_ link to see a summary of your Application's environment. +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. You can also click on the _About your application’s environment_ link to see a summary of your Application's environment. h4. Say "Hello", Rails @@ -310,7 +310,7 @@ Rails will create several files for you, including +app/views/home/index.html.er h4. Setting the Application Home Page -Now that we have made the controller and view, we need to tell Rails when we want "Hello Rails" to show up. In our case, we want it to show up when we navigate to the root URL of our site, "http://localhost:3000":http://localhost:3000, instead of the "Welcome Aboard" smoke test. +Now that we have made the controller and view, we need to tell Rails when we want "Hello Rails" to show up. In our case, we want it to show up when we navigate to the root URL of our site, "http://localhost:3000":http://localhost:3000, instead of the "Welcome Aboard" smoke test. The first step to doing this is to delete the default page from your application: @@ -394,7 +394,7 @@ class CreatePosts < ActiveRecord::Migration end -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. +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: @@ -548,7 +548,7 @@ This view iterates over the contents of the +@posts+ array to display content an * +link_to+ builds a hyperlink to a particular destination * +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 %>+. +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 %>+. TIP: For more details on the rendering process, see "Layouts and Rendering in Rails":layouts_and_rendering.html. @@ -600,7 +600,7 @@ The +new.html.erb+ view displays this empty Post to the user: <%= link_to 'Back', posts_path %> -The +<%= render 'form' %>+ line is our first introduction to _partials_ in Rails. A partial is a snippet of HTML and Ruby code that can be reused in multiple locations. In this case, the form used to make a new post, is basically identical to a form used to edit a post, both have text fields for the name and title and a text area for the content with a button to make a new post or update the existing post. +The +<%= render 'form' %>+ line is our first introduction to _partials_ in Rails. A partial is a snippet of HTML and Ruby code that can be reused in multiple locations. In this case, the form used to make a new post, is basically identical to a form used to edit a post, both have text fields for the name and title and a text area for the content with a button to make a new post or update the existing post. If you take a look at +views/posts/_form.html.erb+ file, you will see the following: @@ -873,7 +873,7 @@ TIP: For more information on Active Record associations, see the "Active Record h4. 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: +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: resources :posts do @@ -901,7 +901,7 @@ This creates four files and one empty directory: * +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. +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: @@ -1078,7 +1078,7 @@ Then in the +app/views/posts/show.html.erb+ you can change it to look like the f <%= 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. +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. h4. Rendering a Partial Form @@ -1138,7 +1138,7 @@ The +@post+ object is available to any partials rendered in the view because we h3. 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+. +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: @@ -1312,7 +1312,7 @@ Note that we have changed the +f+ in +form_for(@post) do |f|+ to +post_form+ to 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 @post.tags.build 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. +We also add a @post.tags.build 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. Now create the folder app/views/tags and make a file in there called _form.html.erb which contains the form for the tag: @@ -1373,7 +1373,7 @@ However, that method call @post.tags.map { |t| t.name }.join(", ") is a h3. View Helpers -View Helpers live in app/helpers and provide small snippets of reusable code for views. In our case, we want a method that strings a bunch of objects together using their name attribute and joining them with a comma. As this is for the Post show template, we put it in the PostsHelper. +View Helpers live in app/helpers and provide small snippets of reusable code for views. In our case, we want a method that strings a bunch of objects together using their name attribute and joining them with a comma. As this is for the Post show template, we put it in the PostsHelper. Open up app/helpers/posts_helper.rb and add the following: diff --git a/railties/guides/source/i18n.textile b/railties/guides/source/i18n.textile index 3e7e396e8d..543fe85f70 100644 --- a/railties/guides/source/i18n.textile +++ b/railties/guides/source/i18n.textile @@ -91,7 +91,7 @@ This means, that in the +:en+ locale, the key _hello_ will map to the _Hello wor The I18n library will use *English* as a *default locale*, i.e. if you don't set a different locale, +:en+ will be used for looking up translations. -NOTE: The i18n library takes a *pragmatic approach* to locale keys (after "some discussion":http://groups.google.com/group/rails-i18n/browse_thread/thread/14dede2c7dbe9470/80eec34395f64f3c?hl=en), including only the _locale_ ("language") part, like +:en+, +:pl+, not the _region_ part, like +:en-US+ or +:en-UK+, which are traditionally used for separating "languages" and "regional setting" or "dialects". Many international applications use only the "language" element of a locale such as +:cz+, +:th+ or +:es+ (for Czech, Thai and Spanish). However, there are also regional differences within different language groups that may be important. For instance, in the +:en-US+ locale you would have $ as a currency symbol, while in +:en-UK+, you would have £. Nothing stops you from separating regional and other settings in this way: you just have to provide full "English - United Kingdom" locale in a +:en-UK+ dictionary. Various "Rails I18n plugins":http://rails-i18n.org/wiki such as "Globalize2":https://github.com/joshmh/globalize2/tree/master may help you implement it. +NOTE: The i18n library takes a *pragmatic approach* to locale keys (after "some discussion":http://groups.google.com/group/rails-i18n/browse_thread/thread/14dede2c7dbe9470/80eec34395f64f3c?hl=en), including only the _locale_ ("language") part, like +:en+, +:pl+, not the _region_ part, like +:en-US+ or +:en-UK+, which are traditionally used for separating "languages" and "regional setting" or "dialects". Many international applications use only the "language" element of a locale such as +:cz+, +:th+ or +:es+ (for Czech, Thai and Spanish). However, there are also regional differences within different language groups that may be important. For instance, in the +:en-US+ locale you would have $ as a currency symbol, while in +:en-UK+, you would have £. Nothing stops you from separating regional and other settings in this way: you just have to provide full "English - United Kingdom" locale in a +:en-UK+ dictionary. Various "Rails I18n plugins":http://rails-i18n.org/wiki such as "Globalize2":https://github.com/joshmh/globalize2/tree/master may help you implement it. The *translations load path* (+I18n.load_path+) is just a Ruby Array of paths to your translation files that will be loaded automatically and available in your application. You can pick whatever directory and translation file naming scheme makes sense for you. @@ -441,7 +441,7 @@ Do check the "Rails i18n Wiki":http://rails-i18n.org/wiki for list of tools avai h3. Overview of the I18n API Features -You should have good understanding of using the i18n library now, knowing all necessary aspects of internationalizing a basic Rails application. In the following chapters, we'll cover it's features in more depth. +You should have good understanding of using the i18n library now, knowing all necessary aspects of internationalizing a basic Rails application. In the following chapters, we'll cover it's features in more depth. Covered are features like these: diff --git a/railties/guides/source/initialization.textile b/railties/guides/source/initialization.textile index 013eca2a35..638830cd83 100644 --- a/railties/guides/source/initialization.textile +++ b/railties/guides/source/initialization.textile @@ -1009,7 +1009,7 @@ The loading of this file finishes the loading of +active_model+ and so we go bac h4. Back to +activesupport/lib/action_dispatch.rb+ -The remainder of this file requires the +rack+ file from the Rack gem which defines the +Rack+ module. After +rack+, there's autoloads defined for the +Rack+, +ActionDispatch+, +ActionDispatch::Http+, +ActionDispatch::Session+. A new method called +autoload_under+ is used here, and this simply prefixes the files where the modules are autoloaded from with the path specified. For example here: +The remainder of this file requires the +rack+ file from the Rack gem which defines the +Rack+ module. After +rack+, there's autoloads defined for the +Rack+, +ActionDispatch+, +ActionDispatch::Http+, +ActionDispatch::Session+. A new method called +autoload_under+ is used here, and this simply prefixes the files where the modules are autoloaded from with the path specified. For example here: autoload_under 'testing' do diff --git a/railties/guides/source/layouts_and_rendering.textile b/railties/guides/source/layouts_and_rendering.textile index 1548da0eb5..66e8aa67e8 100644 --- a/railties/guides/source/layouts_and_rendering.textile +++ b/railties/guides/source/layouts_and_rendering.textile @@ -406,7 +406,7 @@ end Now, if the current user is a special user, they'll get a special layout when viewing a product. You can even use an inline method to determine the layout: -You can also decide the layout by passing a Proc object, the block you give the Proc will be given the +controller+ instance, so you can make decisions based on the current request. For example: +You can also decide the layout by passing a Proc object, the block you give the Proc will be given the +controller+ instance, so you can make decisions based on the current request. For example: class ProductsController < ApplicationController @@ -584,7 +584,7 @@ With this code, the browser will make a fresh request for the index page, the co The only downside to this code, is that it requires a round trip to the browser, the browser requested the show action with +/books/1+ and the controller finds that there are no books, so the controller sends out a 302 redirect response to the browser telling it to go to +/books/+, the browser complies and sends a new request back to the controller asking now for the +index+ action, the controller then gets all the books in the database and renders the index template, sending it back down to the browser which then shows it on your screen. -While in a small app, this added latency might not be a problem, it is something to think about when speed of response is of the essence. One way to handle this double request (though a contrived example) could be: +While in a small app, this added latency might not be a problem, it is something to think about when speed of response is of the essence. One way to handle this double request (though a contrived example) could be: def index @@ -862,7 +862,7 @@ Produces -removes the +description+ and +name+ columns, creates a +part_number+ column and adds an index on it. Finally it renames the +upccode+ column. This is the same as doing +removes the +description+ and +name+ columns, creates a +part_number+ column and adds an index on it. Finally it renames the +upccode+ column. This is the same as doing remove_column :products, :description @@ -335,7 +335,7 @@ NOTE: The +references+ helper does not actually create foreign key constraints f If the helpers provided by Active Record aren't enough you can use the +execute+ function to execute arbitrary SQL. -For more details and examples of individual methods check the API documentation, in particular the documentation for "ActiveRecord::ConnectionAdapters::SchemaStatements":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html (which provides the methods available in the +up+ and +down+ methods), "ActiveRecord::ConnectionAdapters::TableDefinition":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/TableDefinition.html (which provides the methods available on the object yielded by +create_table+) and "ActiveRecord::ConnectionAdapters::Table":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/Table.html (which provides the methods available on the object yielded by +change_table+). +For more details and examples of individual methods check the API documentation, in particular the documentation for "ActiveRecord::ConnectionAdapters::SchemaStatements":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html (which provides the methods available in the +up+ and +down+ methods), "ActiveRecord::ConnectionAdapters::TableDefinition":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/TableDefinition.html (which provides the methods available on the object yielded by +create_table+) and "ActiveRecord::ConnectionAdapters::Table":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/Table.html (which provides the methods available on the object yielded by +change_table+). h4. Writing Your +down+ Method diff --git a/railties/guides/source/plugins.textile b/railties/guides/source/plugins.textile index 31158d8742..d486e8ade3 100644 --- a/railties/guides/source/plugins.textile +++ b/railties/guides/source/plugins.textile @@ -27,7 +27,7 @@ h3. Setup h4. Generating the Plugin Skeleton -Rails currently ships with a generator to generate a plugin within a Rails application. Help text is available that will explain +Rails currently ships with a generator to generate a plugin within a Rails application. Help text is available that will explain how this generator works. @@ -41,7 +41,7 @@ packaging plugins as gems, especially with the inclusion of Bundler as the Rails Packaging a plugin as a gem may be overkill for any plugins that will not be shared across projects but doing so from the start makes it easier to share the plugin going forward without adding too much additional overhead during development. Rails 3.1 will ship with a plugin generator that will default to setting up a plugin -as a gem. This tutorial will begin to bridge that gap by demonstrating how to create a gem based plugin using the +as a gem. This tutorial will begin to bridge that gap by demonstrating how to create a gem based plugin using the "Enginex gem":http://www.github.com/josevalim/enginex. @@ -69,7 +69,7 @@ h3. Extending Core Classes This section will explain how to add a method to String that will be available anywhere in your rails application. -In this example you will add a method to String named +to_squawk+. To begin, create a new test file with a few assertions: +In this example you will add a method to String named +to_squawk+. To begin, create a new test file with a few assertions: # yaffle/test/core_ext_test.rb @@ -83,7 +83,7 @@ class CoreExtTest < Test::Unit::TestCase end -Run +rake+ to run the test. This test should fail because we haven't implemented the +to_squak+ method: +Run +rake+ to run the test. This test should fail because we haven't implemented the +to_squak+ method: 1) Error: @@ -133,7 +133,7 @@ $ rails console h3. Add an "acts_as" Method to Active Record -A common pattern in plugins is to add a method called 'acts_as_something' to models. In this case, you +A common pattern in plugins is to add a method called 'acts_as_something' to models. In this case, you want to write a method called 'acts_as_yaffle' that adds a 'squawk' method to your Active Record models. To begin, set up your files so that you have: @@ -169,9 +169,9 @@ end h4. Add a Class Method -This plugin will expect that you've added a method to your model named 'last_squawk'. However, the +This plugin will expect that you've added a method to your model named 'last_squawk'. However, the plugin users might have already defined a method on their model named 'last_squawk' that they use -for something else. This plugin will allow the name to be changed by adding a class method called 'yaffle_text_field'. +for something else. This plugin will allow the name to be changed by adding a class method called 'yaffle_text_field'. To start out, write a failing test that shows the behavior you'd like: @@ -220,7 +220,7 @@ $ rails generate model Wickwall last_squak:string last_tweet:string Now you can create the necessary database tables in your testing database by navigating to your dummy app -and migrating the database. First +and migrating the database. First $ cd test/dummy @@ -388,17 +388,17 @@ Run +rake+ one final time and you should see: NOTE: The use of +write_attribute+ to write to the field in model is just one example of how a plugin can -interact with the model, and will not always be the right method to use. For example, you could also +interact with the model, and will not always be the right method to use. For example, you could also use +send("#{self.class.yaffle_text_field}=", string.to_squawk)+. h3. Generators -Generators can be included in your gem simply by creating them in a lib/generators directory of your plugin. More information about +Generators can be included in your gem simply by creating them in a lib/generators directory of your plugin. More information about the creation of generators can be found in the "Generators Guide":generators.html h3. Publishing your Gem -Gem plugins in progress can be easily be shared from any Git repository. To share the Yaffle gem with others, simply +Gem plugins in progress can be easily be shared from any Git repository. To share the Yaffle gem with others, simply commit the code to a Git repository (like Github) and add a line to the Gemfile of the any application: @@ -412,7 +412,7 @@ For more information about publishing gems to RubyGems, see: "http://blog.thepet h3. Non-Gem Plugins -Non-gem plugins are useful for functionality that won't be shared with another project. Keeping your custom functionality in the +Non-gem plugins are useful for functionality that won't be shared with another project. Keeping your custom functionality in the vendor/plugins directory un-clutters the rest of the application. Move the directory that you created for the gem based plugin into the vendor/plugins directory of a generated Rails application, create a vendor/plugins/yaffle/init.rb file that contains "require 'yaffle'" and everything will still work. @@ -423,7 +423,7 @@ Move the directory that you created for the gem based plugin into the vendor/plu require 'yaffle' -You can test this by changing to the Rails application that you added the plugin to and starting a rails console. Once in the +You can test this by changing to the Rails application that you added the plugin to and starting a rails console. Once in the console we can check to see if the String has an instance method of to_squawk. $ cd my_app @@ -435,7 +435,7 @@ You can also remove the .gemspec, Gemfile and Gemfile.lock files as they will no h3. RDoc Documentation -Once your plugin is stable and you are ready to deploy do everyone else a favor and document it! Luckily, writing documentation for your plugin is easy. +Once your plugin is stable and you are ready to deploy do everyone else a favor and document it! Luckily, writing documentation for your plugin is easy. The first step is to update the README file with detailed information about how to use your plugin. A few key things to include are: diff --git a/railties/guides/source/routing.textile b/railties/guides/source/routing.textile index 58b75b9a1d..95b877aecf 100644 --- a/railties/guides/source/routing.textile +++ b/railties/guides/source/routing.textile @@ -321,7 +321,7 @@ resources :photos do end -This will recognize +/photos/1/preview+ with GET, and route to the +preview+ action of +PhotosController+. It will also create the +preview_photo_url+ and +preview_photo_path+ helpers. +This will recognize +/photos/1/preview+ with GET, and route to the +preview+ action of +PhotosController+. It will also create the +preview_photo_url+ and +preview_photo_path+ helpers. Within the block of member routes, each route name specifies the HTTP verb that it will recognize. You can use +get+, +put+, +post+, or +delete+ here. If you don't have multiple +member+ routes, you can also pass +:on+ to a route, eliminating the block: @@ -421,7 +421,7 @@ You do not need to explicitly use the +:controller+ and +:action+ symbols within match 'photos/:id' => 'photos#show' -With this route, Rails will match an incoming path of +/photos/12+ to the +show+ action of +PhotosController+. +With this route, Rails will match an incoming path of +/photos/12+ to the +show+ action of +PhotosController+. You can also define other defaults in a route by supplying a hash for the +:defaults+ option. This even applies to parameters that you do not specify as dynamic segments. For example: diff --git a/railties/guides/source/security.textile b/railties/guides/source/security.textile index 893f65856c..2bd7ddf428 100644 --- a/railties/guides/source/security.textile +++ b/railties/guides/source/security.textile @@ -147,7 +147,7 @@ reset_session If you use the popular RestfulAuthentication plugin for user management, add reset_session to the SessionsController#create action. Note that this removes any value from the session, _(highlight)you have to transfer them to the new session_. -Another countermeasure is to _(highlight)save user-specific properties in the session_, verify them every time a request comes in, and deny access, if the information does not match. Such properties could be the remote IP address or the user agent (the web browser name), though the latter is less user-specific. When saving the IP address, you have to bear in mind that there are Internet service providers or large organizations that put their users behind proxies. _(highlight)These might change over the course of a session_, so these users will not be able to use your application, or only in a limited way. +Another countermeasure is to _(highlight)save user-specific properties in the session_, verify them every time a request comes in, and deny access, if the information does not match. Such properties could be the remote IP address or the user agent (the web browser name), though the latter is less user-specific. When saving the IP address, you have to bear in mind that there are Internet service providers or large organizations that put their users behind proxies. _(highlight)These might change over the course of a session_, so these users will not be able to use your application, or only in a limited way. h4. Session Expiry @@ -238,7 +238,7 @@ Or the attacker places the code into the onmouseover event handler of an image: -There are many other possibilities, including Ajax to attack the victim in the background.
The _(highlight)solution to this is including a security token in non-GET requests_ which check on the server-side. In Rails 2 or higher, this is a one-liner in the application controller: +There are many other possibilities, including Ajax to attack the victim in the background.
The _(highlight)solution to this is including a security token in non-GET requests_ which check on the server-side. In Rails 2 or higher, this is a one-liner in the application controller: protect_from_forgery :secret => "123456789012345678901234567890..." @@ -394,7 +394,7 @@ params[:user] # => {:name => “ow3ned”, :admin => true} So if you create a new user using mass-assignment, it may be too easy to become an administrator. -Note that this vulnerability is not restricted to database columns. Any setter method, unless explicitly protected, is accessible via the attributes= method. In fact, this vulnerability is extended even further with the introduction of nested mass assignment (and nested object forms) in Rails 2.3. The +accepts_nested_attributes_for+ declaration provides us the ability to extend mass assignment to model associations (+has_many+, +has_one+, +has_and_belongs_to_many+). For example: +Note that this vulnerability is not restricted to database columns. Any setter method, unless explicitly protected, is accessible via the attributes= method. In fact, this vulnerability is extended even further with the introduction of nested mass assignment (and nested object forms) in Rails 2.3. The +accepts_nested_attributes_for+ declaration provides us the ability to extend mass assignment to model associations (+has_many+, +has_one+, +has_and_belongs_to_many+). For example: class Person < ActiveRecord::Base @@ -434,13 +434,13 @@ params[:user] # => {:name => "ow3ned", :admin => true} @user.admin # => true -A more paranoid technique to protect your whole project would be to enforce that all models whitelist their accessible attributes. This can be easily achieved with a very simple initializer: +A more paranoid technique to protect your whole project would be to enforce that all models whitelist their accessible attributes. This can be easily achieved with a very simple initializer: ActiveRecord::Base.send(:attr_accessible, nil) -This will create an empty whitelist of attributes available for mass assignment for all models in your app. As such, your models will need to explicitly whitelist accessible parameters by using an +attr_accessible+ declaration. This technique is best applied at the start of a new project. However, for an existing project with a thorough set of functional tests, it should be straightforward and relatively quick to insert this initializer, run your tests, and expose each attribute (via +attr_accessible+) as dictated by your failing tests. +This will create an empty whitelist of attributes available for mass assignment for all models in your app. As such, your models will need to explicitly whitelist accessible parameters by using an +attr_accessible+ declaration. This technique is best applied at the start of a new project. However, for an existing project with a thorough set of functional tests, it should be straightforward and relatively quick to insert this initializer, run your tests, and expose each attribute (via +attr_accessible+) as dictated by your failing tests. h3. User Management From ba8a71588d8f3206b92c3e176c0b55529904a488 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Thu, 14 Apr 2011 21:26:20 -0300 Subject: [PATCH 17/59] Added more detailed use of the +list+ command on debugging guide --- .../debugging_rails_applications.textile | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/railties/guides/source/debugging_rails_applications.textile b/railties/guides/source/debugging_rails_applications.textile index 045b8823ca..507b0d7ec9 100644 --- a/railties/guides/source/debugging_rails_applications.textile +++ b/railties/guides/source/debugging_rails_applications.textile @@ -328,6 +328,41 @@ If you repeat the +list+ command, this time using just +l+, the next ten lines o And so on until the end of the current file. When the end of file is reached, the +list+ command will start again from the beginning of the file and continue again up to the end, treating the file as a circular buffer. +On the other hand, to see the previous ten lines you should type +list-+ (or +l-+) + + +(rdb:7) l- +[1, 10] in /PathToProject/posts_controller.rb + 1 class PostsController < ApplicationController + 2 # GET /posts + 3 # GET /posts.xml + 4 def index + 5 debugger + 6 @posts = Post.all + 7 + 8 respond_to do |format| + 9 format.html # index.html.erb + 10 format.xml { render :xml => @posts } + + +This way you can move inside the file, being able to see the code above and over the line you added the +debugger+. +Finally, to see where you are in the code again you can type +list=+ + + +(rdb:7) list= +[1, 10] in /PathToProject/posts_controller.rb + 1 class PostsController < ApplicationController + 2 # GET /posts + 3 # GET /posts.xml + 4 def index + 5 debugger +=> 6 @posts = Post.all + 7 + 8 respond_to do |format| + 9 format.html # index.html.erb + 10 format.xml { render :xml => @posts } + + h4. The Context When you start debugging your application, you will be placed in different contexts as you go through the different parts of the stack. From 4dd84c8db06ddb56468401a478399c995c9604c1 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Fri, 15 Apr 2011 14:08:37 -0300 Subject: [PATCH 18/59] Improved Array#sample documentation --- .../lib/active_support/core_ext/array/random_access.rb | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/activesupport/lib/active_support/core_ext/array/random_access.rb b/activesupport/lib/active_support/core_ext/array/random_access.rb index ab1fa7cd5b..0bf510e39a 100644 --- a/activesupport/lib/active_support/core_ext/array/random_access.rb +++ b/activesupport/lib/active_support/core_ext/array/random_access.rb @@ -1,7 +1,9 @@ class Array # Backport of Array#sample based on Marc-Andre Lafortune's https://github.com/marcandre/backports/ # Returns a random element or +n+ random elements from the array. - # If the array is empty and +n+ is nil, returns nil. if +n+ is passed, returns []. + # If the array is empty and +n+ is nil, returns nil. + # If +n+ is passed and its value is less than 0, it raises an +ArgumentError+ exception. + # If the value of +n+ is equal or greater than 0 it returns []. # # [1,2,3,4,5,6].sample # => 4 # [1,2,3,4,5,6].sample(3) # => [2, 4, 5] From 91761b775ce1f028486dc3483904795e9c028ed6 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Fri, 15 Apr 2011 14:13:10 -0300 Subject: [PATCH 19/59] Added an example of exception situation on Array#sample docs --- .../lib/active_support/core_ext/array/random_access.rb | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/activesupport/lib/active_support/core_ext/array/random_access.rb b/activesupport/lib/active_support/core_ext/array/random_access.rb index 0bf510e39a..9eba4642b8 100644 --- a/activesupport/lib/active_support/core_ext/array/random_access.rb +++ b/activesupport/lib/active_support/core_ext/array/random_access.rb @@ -5,10 +5,11 @@ class Array # If +n+ is passed and its value is less than 0, it raises an +ArgumentError+ exception. # If the value of +n+ is equal or greater than 0 it returns []. # - # [1,2,3,4,5,6].sample # => 4 - # [1,2,3,4,5,6].sample(3) # => [2, 4, 5] - # [].sample # => nil - # [].sample(3) # => [] + # [1,2,3,4,5,6].sample # => 4 + # [1,2,3,4,5,6].sample(3) # => [2, 4, 5] + # [1,2,3,4,5,6].sample(-3) # => ArgumentError: negative sample number + # [].sample # => nil + # [].sample(3) # => [] def sample(n=nil) return self[Kernel.rand(size)] if n.nil? n = n.to_int From 3ca6d0e8fe72f6840049f7c2461243cf362b9896 Mon Sep 17 00:00:00 2001 From: Matt Duncan Date: Fri, 15 Apr 2011 19:56:48 -0400 Subject: [PATCH 20/59] Including actual usage in example --- actionpack/lib/action_view/helpers/date_helper.rb | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/actionpack/lib/action_view/helpers/date_helper.rb b/actionpack/lib/action_view/helpers/date_helper.rb index 6cd1565031..72ee31a246 100644 --- a/actionpack/lib/action_view/helpers/date_helper.rb +++ b/actionpack/lib/action_view/helpers/date_helper.rb @@ -115,7 +115,9 @@ def distance_of_time_in_words(from_time, to_time = 0, include_seconds = false, o # time_ago_in_words(Time.now - 15.hours) # => 15 hours # time_ago_in_words(Time.now) # => less than a minute # - # from_time = Time.now - 3.days - 14.minutes - 25.seconds # => 3 days + # from_time = Time.now - 3.days - 14.minutes - 25.seconds + # time_ago_in_words(from_time) # => 3 days + # def time_ago_in_words(from_time, include_seconds = false) distance_of_time_in_words(from_time, Time.now, include_seconds) end From 8ac365f47626fd4d9569cf9c378c3a8f4f60eb58 Mon Sep 17 00:00:00 2001 From: Matt Duncan Date: Fri, 15 Apr 2011 20:03:52 -0400 Subject: [PATCH 21/59] Making example result match actual result --- actionpack/lib/action_view/helpers/date_helper.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/actionpack/lib/action_view/helpers/date_helper.rb b/actionpack/lib/action_view/helpers/date_helper.rb index 72ee31a246..4c65ebc1f3 100644 --- a/actionpack/lib/action_view/helpers/date_helper.rb +++ b/actionpack/lib/action_view/helpers/date_helper.rb @@ -112,7 +112,7 @@ def distance_of_time_in_words(from_time, to_time = 0, include_seconds = false, o # # ==== Examples # time_ago_in_words(3.minutes.from_now) # => 3 minutes - # time_ago_in_words(Time.now - 15.hours) # => 15 hours + # time_ago_in_words(Time.now - 15.hours) # => about 15 hours # time_ago_in_words(Time.now) # => less than a minute # # from_time = Time.now - 3.days - 14.minutes - 25.seconds From 6ddd4a3d954cd81f96c747f515406be50041431a Mon Sep 17 00:00:00 2001 From: Matt Duncan Date: Fri, 15 Apr 2011 20:08:11 -0400 Subject: [PATCH 22/59] Days are never approximated using 'about' --- actionpack/lib/action_view/helpers/date_helper.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/actionpack/lib/action_view/helpers/date_helper.rb b/actionpack/lib/action_view/helpers/date_helper.rb index 4c65ebc1f3..3c0c7c319c 100644 --- a/actionpack/lib/action_view/helpers/date_helper.rb +++ b/actionpack/lib/action_view/helpers/date_helper.rb @@ -51,7 +51,7 @@ module DateHelper # distance_of_time_in_words(from_time, from_time + 15.seconds) # => less than a minute # distance_of_time_in_words(from_time, from_time + 15.seconds, true) # => less than 20 seconds # distance_of_time_in_words(from_time, 3.years.from_now) # => about 3 years - # distance_of_time_in_words(from_time, from_time + 60.hours) # => about 3 days + # distance_of_time_in_words(from_time, from_time + 60.hours) # => 3 days # distance_of_time_in_words(from_time, from_time + 45.seconds, true) # => less than a minute # distance_of_time_in_words(from_time, from_time - 45.seconds, true) # => less than a minute # distance_of_time_in_words(from_time, 76.seconds.from_now) # => 1 minute From 7f98b544e3b29c7ffdb8cb4a2ad1da5d1a8c611c Mon Sep 17 00:00:00 2001 From: Matt Duncan Date: Fri, 15 Apr 2011 20:18:30 -0400 Subject: [PATCH 23/59] Negative format example should use a negative number --- actionpack/lib/action_view/helpers/number_helper.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/actionpack/lib/action_view/helpers/number_helper.rb b/actionpack/lib/action_view/helpers/number_helper.rb index 05a9c5b4f1..68ebedd328 100644 --- a/actionpack/lib/action_view/helpers/number_helper.rb +++ b/actionpack/lib/action_view/helpers/number_helper.rb @@ -100,7 +100,7 @@ def number_to_phone(number, options = {}) # number_to_currency(1234567890.506, :precision => 3) # => $1,234,567,890.506 # number_to_currency(1234567890.506, :locale => :fr) # => 1 234 567 890,506 € # - # number_to_currency(1234567890.50, :negative_format => "(%u%n)") + # number_to_currency(-1234567890.50, :negative_format => "(%u%n)") # # => ($1,234,567,890.51) # number_to_currency(1234567890.50, :unit => "£", :separator => ",", :delimiter => "") # # => £1234567890,50 From 004042c0d94f0294e691de46094a665acd852653 Mon Sep 17 00:00:00 2001 From: Matt Duncan Date: Fri, 15 Apr 2011 20:27:05 -0400 Subject: [PATCH 24/59] Fixing missing colon on symbol in example --- actionpack/lib/action_view/helpers/number_helper.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/actionpack/lib/action_view/helpers/number_helper.rb b/actionpack/lib/action_view/helpers/number_helper.rb index 68ebedd328..a150019e5c 100644 --- a/actionpack/lib/action_view/helpers/number_helper.rb +++ b/actionpack/lib/action_view/helpers/number_helper.rb @@ -238,7 +238,7 @@ def number_with_delimiter(number, options = {}) # number_with_precision(111.2345, :precision => 1, :significant => true) # => 100 # number_with_precision(13, :precision => 5, :significant => true) # => 13.000 # number_with_precision(111.234, :locale => :fr) # => 111,234 - # number_with_precision(13, :precision => 5, :significant => true, strip_insignificant_zeros => true) + # number_with_precision(13, :precision => 5, :significant => true, :strip_insignificant_zeros => true) # # => 13 # number_with_precision(389.32314, :precision => 4, :significant => true) # => 389.3 # number_with_precision(1111.2345, :precision => 2, :separator => ',', :delimiter => '.') From e8afe4e1ea9ea4c59368bb84efde785876f25061 Mon Sep 17 00:00:00 2001 From: Matt Duncan Date: Fri, 15 Apr 2011 20:30:51 -0400 Subject: [PATCH 25/59] Making spacing consistent --- actionpack/lib/action_view/helpers/number_helper.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/actionpack/lib/action_view/helpers/number_helper.rb b/actionpack/lib/action_view/helpers/number_helper.rb index a150019e5c..b545031fcc 100644 --- a/actionpack/lib/action_view/helpers/number_helper.rb +++ b/actionpack/lib/action_view/helpers/number_helper.rb @@ -318,7 +318,7 @@ def number_with_precision(number, options = {}) # Non-significant zeros after the fractional separator are stripped out by default (set # :strip_insignificant_zeros to +false+ to change that): # number_to_human_size(1234567890123, :precision => 5) # => "1.1229 TB" - # number_to_human_size(524288000, :precision=>5) # => "500 MB" + # number_to_human_size(524288000, :precision => 5) # => "500 MB" def number_to_human_size(number, options = {}) options.symbolize_keys! @@ -407,7 +407,7 @@ def number_to_human_size(number, options = {}) # Unsignificant zeros after the decimal separator are stripped out by default (set # :strip_insignificant_zeros to +false+ to change that): # number_to_human(12345012345, :significant_digits => 6) # => "12.345 Billion" - # number_to_human(500000000, :precision=>5) # => "500 Million" + # number_to_human(500000000, :precision => 5) # => "500 Million" # # ==== Custom Unit Quantifiers # From f274394afbedd2097d5855f8c2d7d384b46977c3 Mon Sep 17 00:00:00 2001 From: Matt Duncan Date: Fri, 15 Apr 2011 21:34:49 -0400 Subject: [PATCH 26/59] Fixing more spacing inconsistencies --- actionpack/lib/action_view/helpers/date_helper.rb | 2 +- actionpack/lib/action_view/helpers/url_helper.rb | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/actionpack/lib/action_view/helpers/date_helper.rb b/actionpack/lib/action_view/helpers/date_helper.rb index 3c0c7c319c..6dbd2e3e43 100644 --- a/actionpack/lib/action_view/helpers/date_helper.rb +++ b/actionpack/lib/action_view/helpers/date_helper.rb @@ -466,7 +466,7 @@ def select_minute(datetime, options = {}, html_options = {}) # # # Generates a select field for hours with a custom prompt. Use :prompt => true for a # # generic prompt. - # select_hour(13, :prompt =>'Choose hour') + # select_hour(13, :prompt => 'Choose hour') # def select_hour(datetime, options = {}, html_options = {}) DateTimeSelector.new(datetime, options, html_options).select_hour diff --git a/actionpack/lib/action_view/helpers/url_helper.rb b/actionpack/lib/action_view/helpers/url_helper.rb index de75488e72..051d3eb049 100644 --- a/actionpack/lib/action_view/helpers/url_helper.rb +++ b/actionpack/lib/action_view/helpers/url_helper.rb @@ -555,10 +555,10 @@ def mail_to(email_address, name = nil, html_options = {}) # current_page?(:controller => 'shop', :action => 'checkout') # # => true # - # current_page?(:controller => 'shop', :action => 'checkout', :order => 'desc', :page=>'1') + # current_page?(:controller => 'shop', :action => 'checkout', :order => 'desc', :page => '1') # # => true # - # current_page?(:controller => 'shop', :action => 'checkout', :order => 'desc', :page=>'2') + # current_page?(:controller => 'shop', :action => 'checkout', :order => 'desc', :page => '2') # # => false # # current_page?(:controller => 'shop', :action => 'checkout', :order => 'desc') From b6bfcc9115df00620e155a84f80d46342c1fe7ee Mon Sep 17 00:00:00 2001 From: Matt Duncan Date: Fri, 15 Apr 2011 21:50:29 -0400 Subject: [PATCH 27/59] Fix syntax error in example --- actionpack/lib/action_view/helpers/text_helper.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/actionpack/lib/action_view/helpers/text_helper.rb b/actionpack/lib/action_view/helpers/text_helper.rb index bdda1df437..d1c505d2b5 100644 --- a/actionpack/lib/action_view/helpers/text_helper.rb +++ b/actionpack/lib/action_view/helpers/text_helper.rb @@ -19,7 +19,7 @@ module Helpers #:nodoc: # simple_format('Example') # # => "

Example

" # - # simple_format('Example') + # simple_format('Example') # # => "

Example

" # # If you want to escape all content, you should invoke the +h+ method before From 1229904602b8c3b354a144ce33468be408cf9cec Mon Sep 17 00:00:00 2001 From: Matt Duncan Date: Fri, 15 Apr 2011 21:56:01 -0400 Subject: [PATCH 28/59] Removing incorrect example results --- actionpack/lib/action_view/helpers/text_helper.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/actionpack/lib/action_view/helpers/text_helper.rb b/actionpack/lib/action_view/helpers/text_helper.rb index d1c505d2b5..06e2b027da 100644 --- a/actionpack/lib/action_view/helpers/text_helper.rb +++ b/actionpack/lib/action_view/helpers/text_helper.rb @@ -295,11 +295,11 @@ def simple_format(text, html_options={}, options={}) # +link+ as its optional second parameter and the +html_options+ hash # as its optional third parameter: # post_body = "Welcome to my new blog at http://www.myblog.com/. Please e-mail me at me@email.com." - # auto_link(post_body, :urls) # => Once upon\na time + # auto_link(post_body, :urls) # # => "Welcome to my new blog at http://www.myblog.com. # Please e-mail me at me@email.com." # - # auto_link(post_body, :all, :target => "_blank") # => Once upon\na time + # auto_link(post_body, :all, :target => "_blank") # # => "Welcome to my new blog at http://www.myblog.com. # Please e-mail me at me@email.com." def auto_link(text, *args, &block)#link = :all, html = {}, &block) From 50b2eb8cbd6cb923026b8fbb98482e06cdbd21ce Mon Sep 17 00:00:00 2001 From: Matt Duncan Date: Fri, 15 Apr 2011 22:09:23 -0400 Subject: [PATCH 29/59] Fixing another example result --- actionpack/lib/action_view/helpers/sanitize_helper.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/actionpack/lib/action_view/helpers/sanitize_helper.rb b/actionpack/lib/action_view/helpers/sanitize_helper.rb index 0fee34f8a4..841be0a567 100644 --- a/actionpack/lib/action_view/helpers/sanitize_helper.rb +++ b/actionpack/lib/action_view/helpers/sanitize_helper.rb @@ -94,7 +94,7 @@ def strip_tags(html) # # => Please e-mail me at me@email.com. # # strip_links('Blog: Visit.') - # # => Blog: Visit + # # => Blog: Visit. def strip_links(html) self.class.link_sanitizer.sanitize(html) end From 7c9927a4092f18c449538c6656f66ef6c47205f2 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Sat, 16 Apr 2011 16:02:05 -0300 Subject: [PATCH 30/59] Added Using Action View with Rails guide section. --- .../source/action_view_overview.textile | 23 ++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/railties/guides/source/action_view_overview.textile b/railties/guides/source/action_view_overview.textile index 1a81920249..33735b7944 100644 --- a/railties/guides/source/action_view_overview.textile +++ b/railties/guides/source/action_view_overview.textile @@ -20,7 +20,28 @@ Note: Some features of Action View are tied to Active Record, but that doesn't m h3. Using Action View with Rails -TODO... +For each controller there is an associated directory in the app/views directory which holds the template files that make up the views associated with that controller. These files are used to display the view that results from each controller action. + +Let's take a look at what Rails does by default when creating a new resource using the scaffold generator: + + +$ rails generate scaffold post + [...] + invoke scaffold_controller + create app/controllers/posts_controller.rb + invoke erb + create app/views/posts + create app/views/posts/index.html.erb + create app/views/posts/edit.html.erb + create app/views/posts/show.html.erb + create app/views/posts/new.html.erb + create app/views/posts/_form.html.erb + [...] + + +There is a naming convention for views in Rails. Typically, the views share their name with the associated controller action, as you can see above. +For example, the index controller action of the posts_controller.rb will use the index.html.erb view file in the app/views/posts directory. +The complete HTML returned to the client is composed of a combination of this ERB file, a layout template that wraps it, and all the partials that the view may reference. Later on this guide you can find a more detailed documentation of each one of this three components. h3. Using Action View outside of Rails From eecb8385b4901f6c4e9679a5fc9f065a639f9ac7 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Sat, 16 Apr 2011 17:14:46 -0300 Subject: [PATCH 31/59] Added Partials section to ActionView guide. --- .../source/action_view_overview.textile | 97 ++++++++++++++++++- 1 file changed, 95 insertions(+), 2 deletions(-) diff --git a/railties/guides/source/action_view_overview.textile b/railties/guides/source/action_view_overview.textile index 33735b7944..72fcb8c0e6 100644 --- a/railties/guides/source/action_view_overview.textile +++ b/railties/guides/source/action_view_overview.textile @@ -115,9 +115,102 @@ TODO needs a screenshot? I have one - not sure where to put it. h3. Templates, Partials and Layouts -TODO... +As mentioned before, the final HTML output is a composition of three Rails elements: +Templates+, +Partials+ and +Layouts+. +Find below a brief overview of each one of them. -TODO see http://guides.rubyonrails.org/layouts_and_rendering.html +h4. Partials + +Partial templates – usually just called "partials" – are another device for breaking the rendering process into more manageable chunks. With a partial, you can move the code for rendering a particular piece of a response to its own file. + +h5. Naming Partials + +To render a partial as part of a view, you use the +render+ method within the view: + + +<%= render "menu" %> + + +This will render a file named +_menu.html.erb+ at that point within the view is being rendered. Note the leading underscore character: partials are named with a leading underscore to distinguish them from regular views, even though they are referred to without the underscore. This holds true even when you're pulling in a partial from another folder: + + +<%= render "shared/menu" %> + + +That code will pull in the partial from +app/views/shared/_menu.html.erb+. + +h5. Using Partials to Simplify Views + +One way to use partials is to treat them as the equivalent of subroutines: as a way to move details out of a view so that you can grasp what's going on more easily. For example, you might have a view that looked like this: + + +<%= render "shared/ad_banner" %> + +

Products

+ +

Here are a few of our fine products:

+<% @products.each do |product| %> + <%= render :partial => "product", :locals => { :product => product } %> +<% end %> + +<%= render "shared/footer" %> + + +Here, the +_ad_banner.html.erb+ and +_footer.html.erb+ partials could contain content that is shared among many pages in your application. You don't need to see the details of these sections when you're concentrating on a particular page. + +h5. The :as and :object options + +By default ActionView::Partials::PartialRenderer has its object in a local variable with the same name as the template. So, given + + +<%= render :partial => "product" %> + + +within product we'll get @product in the local variable +product+, as if we had written: + + +<%= render :partial => "product", :locals => { :product => @product } %> + + +With the :as option we can specify a different name for said local variable. For example, if we wanted it to be +item+ instead of product+ we'd do: + + +<%= render :partial => "product", :as => 'item' %> + + +The :object option can be used to directly specify which object is rendered into the partial; useful when the template's object is elsewhere, in a different ivar or in a local variable for instance. + +For example, instead of: + + +<%= render :partial => "product", :locals => { :product => @item } %> + + +you'd do: + + +<%= render :partial => "product", :object => @item %> + + +The :object and :as options can be used together. + +h5. Rendering Collections + +The example of partial use describes a familiar pattern where a template needs to iterate over an array and render a sub template for each of the elements. This pattern has been implemented as a single method that accepts an array and renders a partial by the same name as the elements contained within. +So the three-lined example for rendering all the products can be rewritten with a single line: + + +<%= render :partial => "product", :collection => @products %> + + +When a partial is called with a pluralized collection, then the individual instances of the partial have access to the member of the collection being rendered via a variable named after the partial. In this case, the partial is +_product+ , and within the +_product+ partial, you can refer to +product+ to get the instance that is being rendered. + +You can use a shorthand syntax for rendering collections. Assuming @products is a collection of +Product+ instances, you can simply write the following to produce the same result: + + +<%= render @products %> + + +Rails determines the name of the partial to use by looking at the model name in the collection. In fact, you can even create a heterogeneous collection and render it this way, and Rails will choose the proper partial for each member of the collection. h3. Using Templates, Partials and Layouts in "The Rails Way" From 143ed7edc32f875882f972ce444c9fa8ea028326 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Sat, 16 Apr 2011 17:32:04 -0300 Subject: [PATCH 32/59] Added Spacer Templates on Partials section of ActionView guide. --- railties/guides/source/action_view_overview.textile | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/railties/guides/source/action_view_overview.textile b/railties/guides/source/action_view_overview.textile index 72fcb8c0e6..ab9b910270 100644 --- a/railties/guides/source/action_view_overview.textile +++ b/railties/guides/source/action_view_overview.textile @@ -212,6 +212,16 @@ You can use a shorthand syntax for rendering collections. Assuming @products is Rails determines the name of the partial to use by looking at the model name in the collection. In fact, you can even create a heterogeneous collection and render it this way, and Rails will choose the proper partial for each member of the collection. +h5. Spacer Templates + +You can also specify a second partial to be rendered between instances of the main partial by using the +:spacer_template+ option: + + +<%= render @products, :spacer_template => "product_ruler" %> + + +Rails will render the +_product_ruler+ partial (with no data passed in to it) between each pair of +_product+ partials. + h3. Using Templates, Partials and Layouts in "The Rails Way" TODO... From 8c68bcf829ead305e2459c2b90850b43464ec7d7 Mon Sep 17 00:00:00 2001 From: Michal Papis Date: Sat, 16 Apr 2011 22:56:58 +0200 Subject: [PATCH 33/59] Added information about grouping conditional validations --- .../active_record_validations_callbacks.textile | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/railties/guides/source/active_record_validations_callbacks.textile b/railties/guides/source/active_record_validations_callbacks.textile index 514d0322b9..8882a5705b 100644 --- a/railties/guides/source/active_record_validations_callbacks.textile +++ b/railties/guides/source/active_record_validations_callbacks.textile @@ -552,6 +552,21 @@ class Account < ActiveRecord::Base end +h4. Grouping conditional validations + +Sometimes it is useful to have multiple validations use one condition, it can be easily achieved using +with_options+. + + +class User < ActiveRecord::Base + with_options :if => :is_admin? do |admin| + admin.validates_length_of :password, :minimum => 10 + admin.validates_presence_of :email + end +end + + +All validations inside of +with_options+ block will have automatically passed the condition +:if => :is_admin?+ + h3. Creating Custom Validation Methods When the built-in validation helpers are not enough for your needs, you can write your own validation methods. From 558f096115eb123eafcea6df66762ba1c10150a6 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Sat, 16 Apr 2011 18:26:44 -0300 Subject: [PATCH 34/59] Added Templates section on ActionView guide. --- .../source/action_view_overview.textile | 101 ++++++++++++++++++ 1 file changed, 101 insertions(+) diff --git a/railties/guides/source/action_view_overview.textile b/railties/guides/source/action_view_overview.textile index ab9b910270..2e36fd038f 100644 --- a/railties/guides/source/action_view_overview.textile +++ b/railties/guides/source/action_view_overview.textile @@ -118,6 +118,103 @@ h3. Templates, Partials and Layouts As mentioned before, the final HTML output is a composition of three Rails elements: +Templates+, +Partials+ and +Layouts+. Find below a brief overview of each one of them. +h4. Templates + +Action View templates can be written in several ways. If the template file has a .erb extension then it uses a mixture of ERB (included in Ruby) and HTML. If the template file has a .builder extension then a fresh instance of Builder::XmlMarkup library is used. + +Rails supports multiple template systems and uses a file extension to distinguish amongst them. For example, an HTML file using the ERB template system will have .html.erb as a file extension. + +h5. ERB + +Within an ERB template Ruby code can be included using both +<% %>+ and +<%= %>+ tags. The +<% %>+ are used to execute Ruby code that does not return anything, such as conditions, loops or blocks, and the +<%= %>+ tags are used when you want output. + +Consider the following loop for names: + + +Names of all the people +<% @people.each do |person| %> + Name: <%= person.name %>
+<% end %> + + +The loop is setup in regular embedding tags +<% %>+ and the name is written using the output embedding tag +<%= %>+. Note that this is not just a usage suggestion, for Regular output functions like print or puts won't work with ERB templates. So this would be wrong: + + +<%# WRONG %> +Hi, Mr. <% puts "Frodo" %> + + +To suppress leading and trailing whitespaces, you can use +<%-+ +-%>+ interchangeably with +<%+ and +%>+. + +h5. Builder + +Builder templates are a more programmatic alternative to ERB. They are especially useful for generating XML content. An XmlMarkup object named +xml+ is automatically made available to templates with a .builder extension. + +Here are some basic examples: + + +xml.em("emphasized") +xml.em { xml.b("emph & bold") } +xml.a("A Link", "href"=>"http://rubyonrails.org") +xml.target("name"=>"compile", "option"=>"fast") + + +will produce + + +emphasized +emph & bold +A link + + + +Any method with a block will be treated as an XML markup tag with nested markup in the block. For example, the following: + + +xml.div { + xml.h1(@person.name) + xml.p(@person.bio) +} + + +would produce something like: + + +
+

David Heinemeier Hansson

+

A product of Danish Design during the Winter of '79...

+
+ + +A full-length RSS example actually used on Basecamp: + + +xml.rss("version" => "2.0", "xmlns:dc" => "http://purl.org/dc/elements/1.1/") do + xml.channel do + xml.title(@feed_title) + xml.link(@url) + xml.description "Basecamp: Recent items" + xml.language "en-us" + xml.ttl "40" + + for item in @recent_items + xml.item do + xml.title(item_title(item)) + xml.description(item_description(item)) if item_description(item) + xml.pubDate(item_pubDate(item)) + xml.guid(@person.firm.account.url + @recent_items.url(item)) + xml.link(@person.firm.account.url + @recent_items.url(item)) + xml.tag!("dc:creator", item.author_name) if item_has_creator?(item) + end + end + end +end + + +h5. Template caching + +By default, Rails will compile each template to a method in order to render it. When you alter a template, Rails will check the file's modification time and recompile it in development mode. + h4. Partials Partial templates – usually just called "partials" – are another device for breaking the rendering process into more manageable chunks. With a partial, you can move the code for rendering a particular piece of a response to its own file. @@ -222,6 +319,10 @@ You can also specify a second partial to be rendered between instances of the ma Rails will render the +_product_ruler+ partial (with no data passed in to it) between each pair of +_product+ partials. +h4. Layouts + +TODO... + h3. Using Templates, Partials and Layouts in "The Rails Way" TODO... From 9c861e8a0e2f21959ede5f71b56f8a50996d6416 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Sat, 16 Apr 2011 18:29:55 -0300 Subject: [PATCH 35/59] Better formatting --- railties/guides/source/action_view_overview.textile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/railties/guides/source/action_view_overview.textile b/railties/guides/source/action_view_overview.textile index 2e36fd038f..ff581217d4 100644 --- a/railties/guides/source/action_view_overview.textile +++ b/railties/guides/source/action_view_overview.textile @@ -227,13 +227,13 @@ To render a partial as part of a view, you use the +render+ method within the vi <%= render "menu" %> -This will render a file named +_menu.html.erb+ at that point within the view is being rendered. Note the leading underscore character: partials are named with a leading underscore to distinguish them from regular views, even though they are referred to without the underscore. This holds true even when you're pulling in a partial from another folder: +This will render a file named _menu.html.erb at that point within the view is being rendered. Note the leading underscore character: partials are named with a leading underscore to distinguish them from regular views, even though they are referred to without the underscore. This holds true even when you're pulling in a partial from another folder: <%= render "shared/menu" %> -That code will pull in the partial from +app/views/shared/_menu.html.erb+. +That code will pull in the partial from app/views/shared/_menu.html.erb. h5. Using Partials to Simplify Views @@ -252,7 +252,7 @@ One way to use partials is to treat them as the equivalent of subroutines: as a <%= render "shared/footer" %> -Here, the +_ad_banner.html.erb+ and +_footer.html.erb+ partials could contain content that is shared among many pages in your application. You don't need to see the details of these sections when you're concentrating on a particular page. +Here, the _ad_banner.html.erb and _footer.html.erb partials could contain content that is shared among many pages in your application. You don't need to see the details of these sections when you're concentrating on a particular page. h5. The :as and :object options From 8606fff6f125822c5c27c053ab13b1c3b26838c8 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Sat, 16 Apr 2011 20:09:54 -0300 Subject: [PATCH 36/59] Added CHANGELOG entry for new section additions on ActionView guide --- railties/guides/source/action_view_overview.textile | 1 + 1 file changed, 1 insertion(+) diff --git a/railties/guides/source/action_view_overview.textile b/railties/guides/source/action_view_overview.textile index ff581217d4..e11cb00d9f 100644 --- a/railties/guides/source/action_view_overview.textile +++ b/railties/guides/source/action_view_overview.textile @@ -1697,5 +1697,6 @@ You can read more about the Rails Internationalization (I18n) API "here":i18n.ht h3. Changelog +* April 16, 2011: Added 'Using Action View with Rails', 'Templates' and 'Partials' sections. "Sebastian Martinez":http://wyeworks.com * September 3, 2009: Continuing work by Trevor Turk, leveraging the Action Pack docs and "What's new in Edge Rails":http://ryandaigle.com/articles/2007/8/3/what-s-new-in-edge-rails-partials-get-layouts * April 5, 2009: Starting work by Trevor Turk, leveraging Mike Gunderloy's docs From 38e77879e0c4d908c8f74c2828bbce7c6c543934 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Sun, 17 Apr 2011 13:06:48 -0300 Subject: [PATCH 37/59] Remove 2.3 since guides are supposed to be for Rails 3 --- railties/guides/source/i18n.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/railties/guides/source/i18n.textile b/railties/guides/source/i18n.textile index 543fe85f70..24ad74485e 100644 --- a/railties/guides/source/i18n.textile +++ b/railties/guides/source/i18n.textile @@ -520,7 +520,7 @@ I18n.t 'activerecord.errors.messages' h5. "Lazy" Lookup -Rails 2.3 implements a convenient way to look up the locale inside _views_. When you have the following dictionary: +Rails implements a convenient way to look up the locale inside _views_. When you have the following dictionary: es: From bd302542d0993a4965c870de607051748b6de0be Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Sun, 17 Apr 2011 19:36:56 -0300 Subject: [PATCH 38/59] Documented NilClass#blank? --- activesupport/lib/active_support/core_ext/object/blank.rb | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/activesupport/lib/active_support/core_ext/object/blank.rb b/activesupport/lib/active_support/core_ext/object/blank.rb index d0c1ea8326..76450a9238 100644 --- a/activesupport/lib/active_support/core_ext/object/blank.rb +++ b/activesupport/lib/active_support/core_ext/object/blank.rb @@ -37,7 +37,11 @@ def presence end end -class NilClass #:nodoc: +class NilClass + # Instances of NilClass are always blank + # Example: + # + # nil.blank? => true def blank? true end From a48d2a7a070540b60d50b14a201ffeba02e390f8 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Sun, 17 Apr 2011 19:38:32 -0300 Subject: [PATCH 39/59] Documented FalseClass#blank? --- activesupport/lib/active_support/core_ext/object/blank.rb | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/activesupport/lib/active_support/core_ext/object/blank.rb b/activesupport/lib/active_support/core_ext/object/blank.rb index 76450a9238..57944bd271 100644 --- a/activesupport/lib/active_support/core_ext/object/blank.rb +++ b/activesupport/lib/active_support/core_ext/object/blank.rb @@ -47,7 +47,11 @@ def blank? end end -class FalseClass #:nodoc: +class FalseClass + # Instances of FalseClass are always blank + # Example: + # + # false.blank? => true def blank? true end From c49799923098b63e906af955dc077cb24caeb659 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Sun, 17 Apr 2011 19:39:40 -0300 Subject: [PATCH 40/59] Documented TrueClass#blank? --- activesupport/lib/active_support/core_ext/object/blank.rb | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/activesupport/lib/active_support/core_ext/object/blank.rb b/activesupport/lib/active_support/core_ext/object/blank.rb index 57944bd271..764d0666fd 100644 --- a/activesupport/lib/active_support/core_ext/object/blank.rb +++ b/activesupport/lib/active_support/core_ext/object/blank.rb @@ -57,7 +57,11 @@ def blank? end end -class TrueClass #:nodoc: +class TrueClass + # Instances of TrueClass are never blank + # Example: + # + # true.blank? => false def blank? false end From ceeed213a96d2f893838f9304b3953a1fc727cfc Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Sun, 17 Apr 2011 19:42:53 -0300 Subject: [PATCH 41/59] Documented Array#blank? --- activesupport/lib/active_support/core_ext/object/blank.rb | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/activesupport/lib/active_support/core_ext/object/blank.rb b/activesupport/lib/active_support/core_ext/object/blank.rb index 764d0666fd..d6f0056ba4 100644 --- a/activesupport/lib/active_support/core_ext/object/blank.rb +++ b/activesupport/lib/active_support/core_ext/object/blank.rb @@ -67,7 +67,12 @@ def blank? end end -class Array #:nodoc: +class Array + # An array is blank if it's empty + # For example: + # + # [].blank? => true + # [1,2,3].blank? => false alias_method :blank?, :empty? end From b14b058be863e5a557191c9b403cc7ebc77951c9 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Sun, 17 Apr 2011 19:44:34 -0300 Subject: [PATCH 42/59] Documented Hash#blank? --- activesupport/lib/active_support/core_ext/object/blank.rb | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/activesupport/lib/active_support/core_ext/object/blank.rb b/activesupport/lib/active_support/core_ext/object/blank.rb index d6f0056ba4..8cef3e87ea 100644 --- a/activesupport/lib/active_support/core_ext/object/blank.rb +++ b/activesupport/lib/active_support/core_ext/object/blank.rb @@ -76,7 +76,12 @@ class Array alias_method :blank?, :empty? end -class Hash #:nodoc: +class Hash + # A hash is blank if it's empty + # For example: + # + # {}.blank? => true + # {:key => 'value'}.blank? => false alias_method :blank?, :empty? end From d0635b6ad43dd08fe2fc505388b4cd229e25845f Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Sun, 17 Apr 2011 19:47:46 -0300 Subject: [PATCH 43/59] Documented String#blank? --- activesupport/lib/active_support/core_ext/object/blank.rb | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/activesupport/lib/active_support/core_ext/object/blank.rb b/activesupport/lib/active_support/core_ext/object/blank.rb index 8cef3e87ea..5cf49e2cbf 100644 --- a/activesupport/lib/active_support/core_ext/object/blank.rb +++ b/activesupport/lib/active_support/core_ext/object/blank.rb @@ -85,7 +85,13 @@ class Hash alias_method :blank?, :empty? end -class String #:nodoc: +class String + # A string is blank if it's empty or contains whitespaces only + # For example: + # + # "".blank? => true + # " ".blank? => true + # " something here ".blank? => false def blank? self !~ /\S/ end From 0675047d79912b11a387941e7968d4a651f0cd48 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Sun, 17 Apr 2011 20:12:39 -0300 Subject: [PATCH 44/59] Formatting examples --- .../active_support/core_ext/object/blank.rb | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/activesupport/lib/active_support/core_ext/object/blank.rb b/activesupport/lib/active_support/core_ext/object/blank.rb index 5cf49e2cbf..be22d7534e 100644 --- a/activesupport/lib/active_support/core_ext/object/blank.rb +++ b/activesupport/lib/active_support/core_ext/object/blank.rb @@ -39,7 +39,8 @@ def presence class NilClass # Instances of NilClass are always blank - # Example: + # + # === Example # # nil.blank? => true def blank? @@ -49,7 +50,8 @@ def blank? class FalseClass # Instances of FalseClass are always blank - # Example: + # + # === Example # # false.blank? => true def blank? @@ -59,7 +61,8 @@ def blank? class TrueClass # Instances of TrueClass are never blank - # Example: + # + # === Example # # true.blank? => false def blank? @@ -69,7 +72,8 @@ def blank? class Array # An array is blank if it's empty - # For example: + # + # === Examples # # [].blank? => true # [1,2,3].blank? => false @@ -78,7 +82,8 @@ class Array class Hash # A hash is blank if it's empty - # For example: + # + # === Examples # # {}.blank? => true # {:key => 'value'}.blank? => false @@ -87,7 +92,8 @@ class Hash class String # A string is blank if it's empty or contains whitespaces only - # For example: + # + # === Examples # # "".blank? => true # " ".blank? => true From bb626e785a9ad32d025e429af24654f2af662d09 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Sun, 17 Apr 2011 20:22:53 -0300 Subject: [PATCH 45/59] Docs for NilClass#try --- .../lib/active_support/core_ext/object/try.rb | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/activesupport/lib/active_support/core_ext/object/try.rb b/activesupport/lib/active_support/core_ext/object/try.rb index 04619124a1..341a6237cb 100644 --- a/activesupport/lib/active_support/core_ext/object/try.rb +++ b/activesupport/lib/active_support/core_ext/object/try.rb @@ -34,7 +34,19 @@ def try(*a, &b) end end -class NilClass #:nodoc: +class NilClass + # Instances of NilClass return always +nil+ + # It becomes specially helpful when navigating through associations that may return nil + # + # === Examples + # + # nil.try(:name) => nil + # + # Without try + # @person && @person.children.first && @person.children.first.name + # + # With try + # @person.try(:children).try(:first).try(:name) def try(*args) nil end From 49e7555a5ed5463fdf13474259e285d41f171da8 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Sun, 17 Apr 2011 20:38:50 -0300 Subject: [PATCH 46/59] Docs for +duplicable?+ --- .../core_ext/object/duplicable.rb | 32 ++++++++++++++++--- 1 file changed, 28 insertions(+), 4 deletions(-) diff --git a/activesupport/lib/active_support/core_ext/object/duplicable.rb b/activesupport/lib/active_support/core_ext/object/duplicable.rb index b05325790c..0f9129d0b6 100644 --- a/activesupport/lib/active_support/core_ext/object/duplicable.rb +++ b/activesupport/lib/active_support/core_ext/object/duplicable.rb @@ -22,25 +22,49 @@ def duplicable? end end -class NilClass #:nodoc: +class NilClass + # Instances of NilClass are not duplicable + # + # === Example + # + # nil.duplicable? # => false + # nil.dup # => TypeError: can't dup NilClass def duplicable? false end end -class FalseClass #:nodoc: +class FalseClass + # Instances of FalseClass are not duplicable + # + # === Example + # + # false.duplicable? # => false + # false.dup # => TypeError: can't dup FalseClass def duplicable? false end end -class TrueClass #:nodoc: +class TrueClass + # Instances of TrueClass are not duplicable + # + # === Example + # + # true.duplicable? # => false + # true.dup # => TypeError: can't dup TrueClass def duplicable? false end end -class Symbol #:nodoc: +class Symbol + # Symbols are not duplicable + # + # === Example + # + # :my_symbol.duplicable? # => false + # :my_symbol.dup # => TypeError: can't dup Symbol def duplicable? false end From 9dfc2153270dcaa2f978ef52fbece99efc150bbc Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Sun, 17 Apr 2011 20:40:33 -0300 Subject: [PATCH 47/59] Formatting docs --- .../active_support/core_ext/object/blank.rb | 20 +++++++++---------- .../lib/active_support/core_ext/object/try.rb | 2 +- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/activesupport/lib/active_support/core_ext/object/blank.rb b/activesupport/lib/active_support/core_ext/object/blank.rb index be22d7534e..b92277f427 100644 --- a/activesupport/lib/active_support/core_ext/object/blank.rb +++ b/activesupport/lib/active_support/core_ext/object/blank.rb @@ -42,7 +42,7 @@ class NilClass # # === Example # - # nil.blank? => true + # nil.blank? # => true def blank? true end @@ -53,7 +53,7 @@ class FalseClass # # === Example # - # false.blank? => true + # false.blank? # => true def blank? true end @@ -64,7 +64,7 @@ class TrueClass # # === Example # - # true.blank? => false + # true.blank? # => false def blank? false end @@ -75,8 +75,8 @@ class Array # # === Examples # - # [].blank? => true - # [1,2,3].blank? => false + # [].blank? # => true + # [1,2,3].blank? # => false alias_method :blank?, :empty? end @@ -85,8 +85,8 @@ class Hash # # === Examples # - # {}.blank? => true - # {:key => 'value'}.blank? => false + # {}.blank? # => true + # {:key => 'value'}.blank? # => false alias_method :blank?, :empty? end @@ -95,9 +95,9 @@ class String # # === Examples # - # "".blank? => true - # " ".blank? => true - # " something here ".blank? => false + # "".blank? # => true + # " ".blank? # => true + # " something here ".blank? # => false def blank? self !~ /\S/ end diff --git a/activesupport/lib/active_support/core_ext/object/try.rb b/activesupport/lib/active_support/core_ext/object/try.rb index 341a6237cb..0977ac51e8 100644 --- a/activesupport/lib/active_support/core_ext/object/try.rb +++ b/activesupport/lib/active_support/core_ext/object/try.rb @@ -40,7 +40,7 @@ class NilClass # # === Examples # - # nil.try(:name) => nil + # nil.try(:name) # => nil # # Without try # @person && @person.children.first && @person.children.first.name From 9556e9c9236eee70c7c69d83893024ccec7587a5 Mon Sep 17 00:00:00 2001 From: Malcolm Locke Date: Mon, 18 Apr 2011 16:02:30 +1200 Subject: [PATCH 48/59] best-of-bread -> best-of-breed --- railties/guides/source/i18n.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/railties/guides/source/i18n.textile b/railties/guides/source/i18n.textile index 24ad74485e..5478a80567 100644 --- a/railties/guides/source/i18n.textile +++ b/railties/guides/source/i18n.textile @@ -863,7 +863,7 @@ If you find anything missing or wrong in this guide, please file a ticket on our h3. Contributing to Rails I18n -I18n support in Ruby on Rails was introduced in the release 2.2 and is still evolving. The project follows the good Ruby on Rails development tradition of evolving solutions in plugins and real applications first, and only then cherry-picking the best-of-bread of most widely useful features for inclusion in the core. +I18n support in Ruby on Rails was introduced in the release 2.2 and is still evolving. The project follows the good Ruby on Rails development tradition of evolving solutions in plugins and real applications first, and only then cherry-picking the best-of-breed of most widely useful features for inclusion in the core. Thus we encourage everybody to experiment with new ideas and features in plugins or other libraries and make them available to the community. (Don't forget to announce your work on our "mailing list":http://groups.google.com/group/rails-i18n!) From af41d5540b0bab8c8cee8cbc7cbfb8fab0676518 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Mon, 18 Apr 2011 09:33:00 -0300 Subject: [PATCH 49/59] Fixed docs for NilClass#try --- .../lib/active_support/core_ext/object/try.rb | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/activesupport/lib/active_support/core_ext/object/try.rb b/activesupport/lib/active_support/core_ext/object/try.rb index 0977ac51e8..c2a3abbc7c 100644 --- a/activesupport/lib/active_support/core_ext/object/try.rb +++ b/activesupport/lib/active_support/core_ext/object/try.rb @@ -9,12 +9,12 @@ class Object # # ==== Examples # - # Without try + # Without +try+ # @person && @person.name # or # @person ? @person.name : nil # - # With try + # With +try+ # @person.try(:name) # # +try+ also accepts arguments and/or a block, for the method it is trying @@ -35,17 +35,17 @@ def try(*a, &b) end class NilClass - # Instances of NilClass return always +nil+ - # It becomes specially helpful when navigating through associations that may return nil + # Instances of +NilClass+ return always +nil+. + # It becomes specially helpful when navigating through associations that may return +nil+. # # === Examples # - # nil.try(:name) # => nil + # nill.try(:name) # => nil # - # Without try - # @person && @person.children.first && @person.children.first.name + # Without +try+ + # @person && !@person.children.blank? && @person.children.first.name # - # With try + # With +try+ # @person.try(:children).try(:first).try(:name) def try(*args) nil From 51f5209dc13afd8399a7f8e7a15041e642d3775b Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Mon, 18 Apr 2011 09:34:51 -0300 Subject: [PATCH 50/59] oops fixed typo --- activesupport/lib/active_support/core_ext/object/try.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/activesupport/lib/active_support/core_ext/object/try.rb b/activesupport/lib/active_support/core_ext/object/try.rb index c2a3abbc7c..aedf5c8c82 100644 --- a/activesupport/lib/active_support/core_ext/object/try.rb +++ b/activesupport/lib/active_support/core_ext/object/try.rb @@ -40,7 +40,7 @@ class NilClass # # === Examples # - # nill.try(:name) # => nil + # nil.try(:name) # => nil # # Without +try+ # @person && !@person.children.blank? && @person.children.first.name From 280a8709923d2bf707ec4d82ac1e5cb14941da3d Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Mon, 18 Apr 2011 10:02:55 -0300 Subject: [PATCH 51/59] Formated docs --- .../active_support/core_ext/object/blank.rb | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/activesupport/lib/active_support/core_ext/object/blank.rb b/activesupport/lib/active_support/core_ext/object/blank.rb index b92277f427..6d14a6dce1 100644 --- a/activesupport/lib/active_support/core_ext/object/blank.rb +++ b/activesupport/lib/active_support/core_ext/object/blank.rb @@ -1,6 +1,6 @@ class Object - # An object is blank if it's false, empty, or a whitespace string. - # For example, "", " ", +nil+, [], and {} are blank. + # An object is +blank+ if it's false, empty, or a whitespace string. + # For example, "", " ", +nil+, [], and {} are +blank+. # # This simplifies: # @@ -18,7 +18,7 @@ def present? !blank? end - # Returns object if it's #present? otherwise returns nil. + # Returns object if it's present? otherwise returns nil. # object.presence is equivalent to object.present? ? object : nil. # # This is handy for any representation of objects where blank is the same @@ -38,7 +38,7 @@ def presence end class NilClass - # Instances of NilClass are always blank + # Instances of +NilClass+ are always +blank+. # # === Example # @@ -49,7 +49,7 @@ def blank? end class FalseClass - # Instances of FalseClass are always blank + # Instances of +FalseClass+ are always +blank+. # # === Example # @@ -60,7 +60,7 @@ def blank? end class TrueClass - # Instances of TrueClass are never blank + # Instances of +TrueClass+ are never +blank+. # # === Example # @@ -71,7 +71,7 @@ def blank? end class Array - # An array is blank if it's empty + # An array is +blank+ if it's +empty+. # # === Examples # @@ -81,7 +81,7 @@ class Array end class Hash - # A hash is blank if it's empty + # A hash is +blank+ if it's +empty+. # # === Examples # @@ -91,7 +91,7 @@ class Hash end class String - # A string is blank if it's empty or contains whitespaces only + # A string is +blank+ if it's empty or contains whitespaces only. # # === Examples # From 082e299e978f705e6ceed747ead3d71ccba36ed4 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Mon, 18 Apr 2011 23:37:27 -0300 Subject: [PATCH 52/59] docs for ActionMailer::Base.default_i18n_subject --- actionmailer/lib/action_mailer/base.rb | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/actionmailer/lib/action_mailer/base.rb b/actionmailer/lib/action_mailer/base.rb index cd76383931..b5d62ad14e 100644 --- a/actionmailer/lib/action_mailer/base.rb +++ b/actionmailer/lib/action_mailer/base.rb @@ -681,7 +681,10 @@ def set_content_type(m, user_content_type, class_default) end end - def default_i18n_subject #:nodoc: + # Translates the +subject+ using Rails I18n class under [:actionmailer, mailer_scope, action_name] scope. + # If it does not find a translation for the +subject+ under the specified scope it will default to a + # humanized version of the action_name. + def default_i18n_subject mailer_scope = self.class.mailer_name.gsub('/', '.') I18n.t(:subject, :scope => [mailer_scope, action_name], :default => action_name.humanize) end From 66a2ffcdb78c74b1d68cd75331d3214b10a8731d Mon Sep 17 00:00:00 2001 From: Paco Guzman Date: Tue, 19 Apr 2011 11:24:09 +0200 Subject: [PATCH 53/59] Update link to Rails 2.3 guides from 2.3.8 to last release 2.3.11. Maybe someone could regenerate the guides --- railties/guides/source/index.html.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/railties/guides/source/index.html.erb b/railties/guides/source/index.html.erb index af46beee56..b48488d8a2 100644 --- a/railties/guides/source/index.html.erb +++ b/railties/guides/source/index.html.erb @@ -17,7 +17,7 @@ Ruby on Rails Guides <% else %>

These are the new guides for Rails 3. The guides for Rails 2.3 are still available - at http://guides.rubyonrails.org/v2.3.8/. + at http://guides.rubyonrails.org/v2.3.11/.

<% end %>

From a1639ad7524127be0a9e9398dc2ccc8c6629adee Mon Sep 17 00:00:00 2001 From: Florent Piteau Date: Tue, 19 Apr 2011 20:44:20 +0200 Subject: [PATCH 54/59] Undocumented :openssl_verify_mode option for smtp_settings --- actionmailer/lib/action_mailer/base.rb | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/actionmailer/lib/action_mailer/base.rb b/actionmailer/lib/action_mailer/base.rb index b5d62ad14e..bf7e50596a 100644 --- a/actionmailer/lib/action_mailer/base.rb +++ b/actionmailer/lib/action_mailer/base.rb @@ -296,6 +296,10 @@ module ActionMailer #:nodoc: # information and a cryptographic Message Digest 5 algorithm to hash important information) # * :enable_starttls_auto - When set to true, detects if STARTTLS is enabled in your SMTP server # and starts to use it. + # * :openssl_verify_mode - When using TLS, you can set how OpenSSL checks the certificate. This is + # really useful if you need to validate a self-signed and/or a wildcard certificate. You can use the name + # of an OpenSSL verify constant ('none', 'peer', 'client_once','fail_if_no_peer_cert') or directly the + # constant (OpenSSL::SSL::VERIFY_NONE, OpenSSL::SSL::VERIFY_PEER,...). # # * sendmail_settings - Allows you to override options for the :sendmail delivery method. # * :location - The location of the sendmail executable. Defaults to /usr/sbin/sendmail. From 3265516c50abe2b6946fc724fa50c1cf522126d3 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Tue, 19 Apr 2011 20:48:39 +0200 Subject: [PATCH 55/59] brings a #:nodoc: back --- actionmailer/lib/action_mailer/base.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/actionmailer/lib/action_mailer/base.rb b/actionmailer/lib/action_mailer/base.rb index bf7e50596a..06de43b76f 100644 --- a/actionmailer/lib/action_mailer/base.rb +++ b/actionmailer/lib/action_mailer/base.rb @@ -688,7 +688,7 @@ def set_content_type(m, user_content_type, class_default) # Translates the +subject+ using Rails I18n class under [:actionmailer, mailer_scope, action_name] scope. # If it does not find a translation for the +subject+ under the specified scope it will default to a # humanized version of the action_name. - def default_i18n_subject + def default_i18n_subject #:nodoc: mailer_scope = self.class.mailer_name.gsub('/', '.') I18n.t(:subject, :scope => [mailer_scope, action_name], :default => action_name.humanize) end From 571b4a2a91fcfb46166349c148326d38999a0d7d Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Tue, 19 Apr 2011 20:51:24 +0200 Subject: [PATCH 56/59] Revert "Formated docs" Reason: "To be blank" and "to be empty" belongs to our everyday terminology, they go in regular font. This reverts commit 280a8709923d2bf707ec4d82ac1e5cb14941da3d. --- .../active_support/core_ext/object/blank.rb | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/activesupport/lib/active_support/core_ext/object/blank.rb b/activesupport/lib/active_support/core_ext/object/blank.rb index 6d14a6dce1..b92277f427 100644 --- a/activesupport/lib/active_support/core_ext/object/blank.rb +++ b/activesupport/lib/active_support/core_ext/object/blank.rb @@ -1,6 +1,6 @@ class Object - # An object is +blank+ if it's false, empty, or a whitespace string. - # For example, "", " ", +nil+, [], and {} are +blank+. + # An object is blank if it's false, empty, or a whitespace string. + # For example, "", " ", +nil+, [], and {} are blank. # # This simplifies: # @@ -18,7 +18,7 @@ def present? !blank? end - # Returns object if it's present? otherwise returns nil. + # Returns object if it's #present? otherwise returns nil. # object.presence is equivalent to object.present? ? object : nil. # # This is handy for any representation of objects where blank is the same @@ -38,7 +38,7 @@ def presence end class NilClass - # Instances of +NilClass+ are always +blank+. + # Instances of NilClass are always blank # # === Example # @@ -49,7 +49,7 @@ def blank? end class FalseClass - # Instances of +FalseClass+ are always +blank+. + # Instances of FalseClass are always blank # # === Example # @@ -60,7 +60,7 @@ def blank? end class TrueClass - # Instances of +TrueClass+ are never +blank+. + # Instances of TrueClass are never blank # # === Example # @@ -71,7 +71,7 @@ def blank? end class Array - # An array is +blank+ if it's +empty+. + # An array is blank if it's empty # # === Examples # @@ -81,7 +81,7 @@ class Array end class Hash - # A hash is +blank+ if it's +empty+. + # A hash is blank if it's empty # # === Examples # @@ -91,7 +91,7 @@ class Hash end class String - # A string is +blank+ if it's empty or contains whitespaces only. + # A string is blank if it's empty or contains whitespaces only # # === Examples # From eaf0d1a491c836ec3c05417613272df423c83bb5 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Tue, 19 Apr 2011 20:58:00 +0200 Subject: [PATCH 57/59] commit copy-edit: simplifies blank? rdoc and revises formatting --- .../active_support/core_ext/object/blank.rb | 47 +++++++++---------- 1 file changed, 23 insertions(+), 24 deletions(-) diff --git a/activesupport/lib/active_support/core_ext/object/blank.rb b/activesupport/lib/active_support/core_ext/object/blank.rb index b92277f427..20085c4fb3 100644 --- a/activesupport/lib/active_support/core_ext/object/blank.rb +++ b/activesupport/lib/active_support/core_ext/object/blank.rb @@ -18,8 +18,8 @@ def present? !blank? end - # Returns object if it's #present? otherwise returns nil. - # object.presence is equivalent to object.present? ? object : nil. + # Returns object if it's present? otherwise returns +nil+. + # object.presence is equivalent to object.present? ? object : nil. # # This is handy for any representation of objects where blank is the same # as not present at all. For example, this simplifies a common check for @@ -38,72 +38,71 @@ def presence end class NilClass - # Instances of NilClass are always blank + # +nil+ is blank: # - # === Example + # nil.blank? # => true # - # nil.blank? # => true def blank? true end end class FalseClass - # Instances of FalseClass are always blank + # +false+ is blank: # - # === Example + # false.blank? # => true # - # false.blank? # => true def blank? true end end class TrueClass - # Instances of TrueClass are never blank + # +true+ is not blank: # - # === Example + # true.blank? # => false # - # true.blank? # => false def blank? false end end class Array - # An array is blank if it's empty + # An array is blank if it's empty: # - # === Examples + # [].blank? # => true + # [1,2,3].blank? # => false # - # [].blank? # => true - # [1,2,3].blank? # => false alias_method :blank?, :empty? end class Hash - # A hash is blank if it's empty + # A hash is blank if it's empty: # - # === Examples + # {}.blank? # => true + # {:key => 'value'}.blank? # => false # - # {}.blank? # => true - # {:key => 'value'}.blank? # => false alias_method :blank?, :empty? end class String - # A string is blank if it's empty or contains whitespaces only + # A string is blank if it's empty or contains whitespaces only: # - # === Examples + # "".blank? # => true + # " ".blank? # => true + # " something here ".blank? # => false # - # "".blank? # => true - # " ".blank? # => true - # " something here ".blank? # => false def blank? self !~ /\S/ end end class Numeric #:nodoc: + # No number is blank: + # + # 1.blank? # => false + # 0.blank? # => false + # def blank? false end From 5fee98adf8ce515a98ddd7d7833ab9d730489bad Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Tue, 19 Apr 2011 21:15:15 +0200 Subject: [PATCH 58/59] remove unwanted Example headers as per the guidelines, s/instaces of NilClass/nil/ and friends, completes some rdocs --- .../core_ext/object/duplicable.rb | 57 ++++++++++++------- 1 file changed, 36 insertions(+), 21 deletions(-) diff --git a/activesupport/lib/active_support/core_ext/object/duplicable.rb b/activesupport/lib/active_support/core_ext/object/duplicable.rb index 0f9129d0b6..02cb5dfee7 100644 --- a/activesupport/lib/active_support/core_ext/object/duplicable.rb +++ b/activesupport/lib/active_support/core_ext/object/duplicable.rb @@ -15,74 +15,89 @@ # That's why we hardcode the following cases and check duplicable? instead of # using that rescue idiom. class Object - # Can you safely .dup this object? - # False for nil, false, true, symbols, numbers, class and module objects; true otherwise. + # Can you safely dup this object? + # + # False for +nil+, +false+, +true+, symbols, numbers, class and module objects; + # true otherwise. def duplicable? true end end class NilClass - # Instances of NilClass are not duplicable + # +nil+ is not duplicable: # - # === Example + # nil.duplicable? # => false + # nil.dup # => TypeError: can't dup NilClass # - # nil.duplicable? # => false - # nil.dup # => TypeError: can't dup NilClass def duplicable? false end end class FalseClass - # Instances of FalseClass are not duplicable + # +false+ is not duplicable: # - # === Example + # false.duplicable? # => false + # false.dup # => TypeError: can't dup FalseClass # - # false.duplicable? # => false - # false.dup # => TypeError: can't dup FalseClass def duplicable? false end end class TrueClass - # Instances of TrueClass are not duplicable + # +true+ is not duplicable: # - # === Example + # true.duplicable? # => false + # true.dup # => TypeError: can't dup TrueClass # - # true.duplicable? # => false - # true.dup # => TypeError: can't dup TrueClass def duplicable? false end end class Symbol - # Symbols are not duplicable + # Symbols are not duplicable: # - # === Example + # :my_symbol.duplicable? # => false + # :my_symbol.dup # => TypeError: can't dup Symbol # - # :my_symbol.duplicable? # => false - # :my_symbol.dup # => TypeError: can't dup Symbol def duplicable? false end end -class Numeric #:nodoc: +class Numeric + # Numbers are not duplicable: + # + # 3.duplicable? # => false + # 3.dup # => TypeError: can't dup Fixnum + # def duplicable? false end end -class Class #:nodoc: +class Class + # Classes are not duplicable: + # + # c = Class.new # => # + # c.dup # => # + # + # Note +dup+ returned the same class object. def duplicable? false end end -class Module #:nodoc: +class Module + # Modules are not duplicable: + # + # m = Module.new # => # + # m.dup # => # + # + # Note +dup+ returned the same module object. def duplicable? false end From ad602869260b4233f7471f8aa467d3b83ffeb801 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Tue, 19 Apr 2011 21:43:17 +0200 Subject: [PATCH 59/59] Revert "Better formatting" No need to change this formatting. This reverts commit 9c861e8a0e2f21959ede5f71b56f8a50996d6416. --- railties/guides/source/action_view_overview.textile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/railties/guides/source/action_view_overview.textile b/railties/guides/source/action_view_overview.textile index e11cb00d9f..172932fdab 100644 --- a/railties/guides/source/action_view_overview.textile +++ b/railties/guides/source/action_view_overview.textile @@ -227,13 +227,13 @@ To render a partial as part of a view, you use the +render+ method within the vi <%= render "menu" %> -This will render a file named _menu.html.erb at that point within the view is being rendered. Note the leading underscore character: partials are named with a leading underscore to distinguish them from regular views, even though they are referred to without the underscore. This holds true even when you're pulling in a partial from another folder: +This will render a file named +_menu.html.erb+ at that point within the view is being rendered. Note the leading underscore character: partials are named with a leading underscore to distinguish them from regular views, even though they are referred to without the underscore. This holds true even when you're pulling in a partial from another folder: <%= render "shared/menu" %> -That code will pull in the partial from app/views/shared/_menu.html.erb. +That code will pull in the partial from +app/views/shared/_menu.html.erb+. h5. Using Partials to Simplify Views @@ -252,7 +252,7 @@ One way to use partials is to treat them as the equivalent of subroutines: as a <%= render "shared/footer" %> -Here, the _ad_banner.html.erb and _footer.html.erb partials could contain content that is shared among many pages in your application. You don't need to see the details of these sections when you're concentrating on a particular page. +Here, the +_ad_banner.html.erb+ and +_footer.html.erb+ partials could contain content that is shared among many pages in your application. You don't need to see the details of these sections when you're concentrating on a particular page. h5. The :as and :object options