diff options
Diffstat (limited to 'guides/source')
| -rw-r--r-- | guides/source/action_view_overview.textile | 50 | ||||
| -rw-r--r-- | guides/source/active_record_querying.textile | 18 | ||||
| -rw-r--r-- | guides/source/active_support_core_extensions.textile | 135 | ||||
| -rw-r--r-- | guides/source/asset_pipeline.textile | 4 | ||||
| -rw-r--r-- | guides/source/configuring.textile | 2 | ||||
| -rw-r--r-- | guides/source/contributing_to_ruby_on_rails.textile | 61 | ||||
| -rw-r--r-- | guides/source/credits.html.erb | 4 | ||||
| -rw-r--r-- | guides/source/debugging_rails_applications.textile | 2 | ||||
| -rw-r--r-- | guides/source/engines.textile | 2 | ||||
| -rw-r--r-- | guides/source/form_helpers.textile | 18 | ||||
| -rw-r--r-- | guides/source/getting_started.textile | 278 | ||||
| -rw-r--r-- | guides/source/initialization.textile | 263 | ||||
| -rw-r--r-- | guides/source/layouts_and_rendering.textile | 6 | ||||
| -rw-r--r-- | guides/source/migrations.textile | 16 | ||||
| -rw-r--r-- | guides/source/rails_on_rack.textile | 66 | ||||
| -rw-r--r-- | guides/source/routing.textile | 10 | ||||
| -rw-r--r-- | guides/source/ruby_on_rails_guides_guidelines.textile | 24 | ||||
| -rw-r--r-- | guides/source/security.textile | 11 | ||||
| -rw-r--r-- | guides/source/upgrading_ruby_on_rails.textile | 20 |
19 files changed, 696 insertions, 294 deletions
diff --git a/guides/source/action_view_overview.textile b/guides/source/action_view_overview.textile index bde30ba21c..734fdd895b 100644 --- a/guides/source/action_view_overview.textile +++ b/guides/source/action_view_overview.textile @@ -542,28 +542,28 @@ image_tag("rails.png") # => <img src="http://assets.example.com/images/rails.png h5. register_javascript_expansion -Register one or more JavaScript files to be included when symbol is passed to javascript_include_tag. This method is typically intended to be called from plugin initialization to register JavaScript files that the plugin installed in +public/javascripts+. +Register one or more JavaScript files to be included when symbol is passed to javascript_include_tag. This method is typically intended to be called from plugin initialization to register JavaScript files that the plugin installed in +vendor/assets/javascripts+. <ruby> ActionView::Helpers::AssetTagHelper.register_javascript_expansion :monkey => ["head", "body", "tail"] javascript_include_tag :monkey # => - <script src="/javascripts/head.js"></script> - <script src="/javascripts/body.js"></script> - <script src="/javascripts/tail.js"></script> + <script src="/assets/head.js"></script> + <script src="/assets/body.js"></script> + <script src="/assets/tail.js"></script> </ruby> h5. register_stylesheet_expansion -Register one or more stylesheet files to be included when symbol is passed to +stylesheet_link_tag+. This method is typically intended to be called from plugin initialization to register stylesheet files that the plugin installed in +public/stylesheets+. +Register one or more stylesheet files to be included when symbol is passed to +stylesheet_link_tag+. This method is typically intended to be called from plugin initialization to register stylesheet files that the plugin installed in +vendor/assets/stylesheets+. <ruby> ActionView::Helpers::AssetTagHelper.register_stylesheet_expansion :monkey => ["head", "body", "tail"] stylesheet_link_tag :monkey # => - <link href="/stylesheets/head.css" media="screen" rel="stylesheet" /> - <link href="/stylesheets/body.css" media="screen" rel="stylesheet" /> - <link href="/stylesheets/tail.css" media="screen" rel="stylesheet" /> + <link href="/assets/head.css" media="screen" rel="stylesheet" /> + <link href="/assets/body.css" media="screen" rel="stylesheet" /> + <link href="/assets/tail.css" media="screen" rel="stylesheet" /> </ruby> h5. auto_discovery_link_tag @@ -577,15 +577,21 @@ auto_discovery_link_tag(:rss, "http://www.example.com/feed.rss", {:title => "RSS h5. image_path -Computes the path to an image asset in the +public/images+ directory. Full paths from the document root will be passed through. Used internally by +image_tag+ to build the image path. +Computes the path to an image asset in the +app/assets/images+ directory. Full paths from the document root will be passed through. Used internally by +image_tag+ to build the image path. <ruby> image_path("edit.png") # => /images/edit.png </ruby> +Fingerprint will be added to the filename if config.assets.digest is set to true. + +<ruby> +image_path("edit.png") # => /images/edit-2d1a2db63fc738690021fedb5a65b68e.png +</ruby> + h5. image_url -Computes the url to an image asset in the +public/images+ directory. This will call +image_path+ internally and merge with your current host or your asset host. +Computes the url to an image asset in the +app/asset/images+ directory. This will call +image_path+ internally and merge with your current host or your asset host. <ruby> image_url("edit.png") # => http://www.example.com/images/edit.png @@ -593,7 +599,7 @@ image_url("edit.png") # => http://www.example.com/images/edit.png h5. image_tag -Returns an html image tag for the source. The source can be a full path or a file that exists in your +public/images+ directory. +Returns an html image tag for the source. The source can be a full path or a file that exists in your +app/assets/images+ directory. <ruby> image_tag("icon.png") # => <img src="/images/icon.png" alt="Icon" /> @@ -601,20 +607,20 @@ image_tag("icon.png") # => <img src="/images/icon.png" alt="Icon" /> h5. javascript_include_tag -Returns an html script tag for each of the sources provided. You can pass in the filename (+.js+ extension is optional) of JavaScript files that exist in your +public/javascripts+ directory for inclusion into the current page or you can pass the full path relative to your document root. +Returns an html script tag for each of the sources provided. You can pass in the filename (+.js+ extension is optional) of JavaScript files that exist in your +app/assets/javascripts+ directory for inclusion into the current page or you can pass the full path relative to your document root. <ruby> javascript_include_tag "common" # => <script src="/javascripts/common.js"></script> </ruby> -If the application does not use the asset pipeline, to include the jQuery JavaScript library in your application, pass +:defaults+ as the source. When using +:defaults+, if an +application.js+ file exists in your +public/javascripts+ directory, it will be included as well. +If the application does not use the asset pipeline, to include the jQuery JavaScript library in your application, pass +:defaults+ as the source. When using +:defaults+, if an +application.js+ file exists in your +app/assets/javascripts+ directory, it will be included as well. <ruby> javascript_include_tag :defaults </ruby> -You can also include all JavaScript files in the +public/javascripts+ directory using +:all+ as the source. +You can also include all JavaScript files in the +app/assets/javascripts+ directory using +:all+ as the source. <ruby> javascript_include_tag :all @@ -629,7 +635,7 @@ javascript_include_tag :all, :cache => true # => h5. javascript_path -Computes the path to a JavaScript asset in the +public/javascripts+ directory. If the source filename has no extension, +.js+ will be appended. Full paths from the document root will be passed through. Used internally by +javascript_include_tag+ to build the script path. +Computes the path to a JavaScript asset in the +app/assets/javascripts+ directory. If the source filename has no extension, +.js+ will be appended. Full paths from the document root will be passed through. Used internally by +javascript_include_tag+ to build the script path. <ruby> javascript_path "common" # => /javascripts/common.js @@ -637,7 +643,7 @@ javascript_path "common" # => /javascripts/common.js h5. javascript_url -Computes the url to a JavaScript asset in the +public/javascripts+ directory. This will call +javascript_path+ internally and merge with your current host or your asset host. +Computes the url to a JavaScript asset in the +app/assets/javascripts+ directory. This will call +javascript_path+ internally and merge with your current host or your asset host. <ruby> javascript_url "common" # => http://www.example.com/javascripts/common.js @@ -649,7 +655,7 @@ Returns a stylesheet link tag for the sources specified as arguments. If you don <ruby> stylesheet_link_tag "application" # => - <link href="/stylesheets/application.css" media="screen" rel="stylesheet" /> + <link href="/assets/application.css" media="screen" rel="stylesheet" /> </ruby> You can also include all styles in the stylesheet directory using :all as the source: @@ -662,23 +668,23 @@ You can also cache multiple stylesheets into one file, which requires less HTTP <ruby> stylesheet_link_tag :all, :cache => true - <link href="/stylesheets/all.css" media="screen" rel="stylesheet" /> + <link href="/assets/all.css" media="screen" rel="stylesheet" /> </ruby> h5. stylesheet_path -Computes the path to a stylesheet asset in the +public/stylesheets+ directory. If the source filename has no extension, .css will be appended. Full paths from the document root will be passed through. Used internally by stylesheet_link_tag to build the stylesheet path. +Computes the path to a stylesheet asset in the +app/assets/stylesheets+ directory. If the source filename has no extension, .css will be appended. Full paths from the document root will be passed through. Used internally by stylesheet_link_tag to build the stylesheet path. <ruby> -stylesheet_path "application" # => /stylesheets/application.css +stylesheet_path "application" # => /assets/application.css </ruby> h5. stylesheet_url -Computes the url to a stylesheet asset in the +public/stylesheets+ directory. This will call +stylesheet_path+ internally and merge with your current host or your asset host. +Computes the url to a stylesheet asset in the +app/assets/stylesheets+ directory. This will call +stylesheet_path+ internally and merge with your current host or your asset host. <ruby> -stylesheet_url "application" # => http://www.example.com/stylesheets/application.css +stylesheet_url "application" # => http://www.example.com/assets/application.css </ruby> h4. AtomFeedHelper diff --git a/guides/source/active_record_querying.textile b/guides/source/active_record_querying.textile index a9cb424eaa..294ef25b33 100644 --- a/guides/source/active_record_querying.textile +++ b/guides/source/active_record_querying.textile @@ -1260,6 +1260,24 @@ with Client.pluck(:id) </ruby> +h3. +ids+ + ++ids+ can be used to pluck all the IDs for the relation using the table's primary key. + +<ruby> +Person.ids +# SELECT id FROM people +</ruby> + +<ruby> +class Person < ActiveRecord::Base + self.primary_key = "person_id" +end + +Person.ids +# SELECT person_id FROM people +</ruby> + h3. Existence of Objects If you simply want to check for the existence of the object there's a method called +exists?+. This method will query the database using the same query as +find+, but instead of returning an object or collection of objects it will return either +true+ or +false+. diff --git a/guides/source/active_support_core_extensions.textile b/guides/source/active_support_core_extensions.textile index afd43ab317..2addc50d68 100644 --- a/guides/source/active_support_core_extensions.textile +++ b/guides/source/active_support_core_extensions.textile @@ -84,7 +84,7 @@ The following values are considered to be blank in a Rails application: * any other object that responds to +empty?+ and it is empty. -INFO: In Ruby 1.9 the predicate for strings uses the Unicode-aware character class <tt>[:space:]</tt>, so for example U+2029 (paragraph separator) is considered to be whitespace. In Ruby 1.8 whitespace is considered to be <tt>\s</tt> together with the ideographic space U+3000. +INFO: The predicate for strings uses the Unicode-aware character class <tt>[:space:]</tt>, so for example U+2029 (paragraph separator) is considered to be whitespace. WARNING: Note that numbers are not mentioned, in particular 0 and 0.0 are *not* blank. @@ -1323,7 +1323,7 @@ Returns the character of the string at position +position+: "hello".at(0) # => "h" "hello".at(4) # => "o" "hello".at(-1) # => "o" -"hello".at(10) # => ERROR if < 1.9, nil in 1.9 +"hello".at(10) # => nil </ruby> NOTE: Defined in +active_support/core_ext/string/access.rb+. @@ -1805,7 +1805,7 @@ NOTE: Defined in +active_support/core_ext/numeric/bytes.rb+. h4. Time -Enables the use of time calculations and declarations, like 45.minutes + 2.hours + 4.years. +Enables the use of time calculations and declarations, like @45.minutes <plus> 2.hours <plus> 4.years@. These methods use Time#advance for precise date calculations when using from_now, ago, etc. as well as adding or subtracting their results from a Time object. For example: @@ -1840,6 +1840,76 @@ date and time arithmetic. NOTE: Defined in +active_support/core_ext/numeric/time.rb+. +h4. Formatting + +Enables the formatting of numbers in a variety of ways. + +Produce a string representation of a number as a telephone number: +<ruby> +5551234.to_s(:phone) # => 555-1234 +1235551234.to_s(:phone) # => 123-555-1234 +1235551234.to_s(:phone, :area_code => true) # => (123) 555-1234 +1235551234.to_s(:phone, :delimiter => " ") # => 123 555 1234 +1235551234.to_s(:phone, :area_code => true, :extension => 555) # => (123) 555-1234 x 555 +1235551234.to_s(:phone, :country_code => 1) # => +1-123-555-1234 +</ruby> + +Produce a string representation of a number as currency: +<ruby> +1234567890.50.to_s(:currency) # => $1,234,567,890.50 +1234567890.506.to_s(:currency) # => $1,234,567,890.51 +1234567890.506.to_s(:currency, :precision => 3) # => $1,234,567,890.506 +</ruby> + +Produce a string representation of a number as a percentage: +<ruby> +100.to_s(:percentage) # => 100.000% +100.to_s(:percentage, :precision => 0) # => 100% +1000.to_s(:percentage, :delimiter => '.', :separator => ',') # => 1.000,000% +302.24398923423.to_s(:percentage, :precision => 5) # => 302.24399% +</ruby> + +Produce a string representation of a number in delimited form: +<ruby> +12345678.to_s(:delimited) # => 12,345,678 +12345678.05.to_s(:delimited) # => 12,345,678.05 +12345678.to_s(:delimited, :delimiter => ".") # => 12.345.678 +12345678.to_s(:delimited, :delimiter => ",") # => 12,345,678 +12345678.05.to_s(:delimited, :separator => " ") # => 12,345,678 05 +</ruby> + +Produce a string representation of a number rounded to a precision: +<ruby> +111.2345.to_s(:rounded) # => 111.235 +111.2345.to_s(:rounded, :precision => 2) # => 111.23 +13.to_s(:rounded, :precision => 5) # => 13.00000 +389.32314.to_s(:rounded, :precision => 0) # => 389 +111.2345.to_s(:rounded, :significant => true) # => 111 +</ruby> + +Produce a string representation of a number as a human-readable number of bytes: +<ruby> +123.to_s(:human_size) # => 123 Bytes +1234.to_s(:human_size) # => 1.21 KB +12345.to_s(:human_size) # => 12.1 KB +1234567.to_s(:human_size) # => 1.18 MB +1234567890.to_s(:human_size) # => 1.15 GB +1234567890123.to_s(:human_size) # => 1.12 TB +</ruby> + +Produce a string representation of a number in human-readable words: +<ruby> +123.to_s(:human) # => "123" +1234.to_s(:human) # => "1.23 Thousand" +12345.to_s(:human) # => "12.3 Thousand" +1234567.to_s(:human) # => "1.23 Million" +1234567890.to_s(:human) # => "1.23 Billion" +1234567890123.to_s(:human) # => "1.23 Trillion" +1234567890123456.to_s(:human) # => "1.23 Quadrillion" +</ruby> + +NOTE: Defined in +active_support/core_ext/numeric/formatting.rb+. + h3. Extensions to +Integer+ h4. +multiple_of?+ @@ -2093,7 +2163,7 @@ h5. +to_formatted_s+ The method +to_formatted_s+ acts like +to_s+ by default. -If the array contains items that respond to +id+, however, it may be passed the symbol <tt>:db</tt> as argument. That's typically used with collections of ARs, though technically any object in Ruby 1.8 responds to +id+ indeed. Returned strings are: +If the array contains items that respond to +id+, however, it may be passed the symbol <tt>:db</tt> as argument. That's typically used with collections of ARs. Returned strings are: <ruby> [].to_formatted_s(:db) # => "null" @@ -2549,6 +2619,45 @@ There's also the bang variant +except!+ that removes keys in the very receiver. NOTE: Defined in +active_support/core_ext/hash/except.rb+. +h5. +transform_keys+ and +transform_keys!+ + +The method +transform_keys+ accepts a block and returns a hash that has applied the block operations to each of the keys in the receiver: + +<ruby> +{nil => nil, 1 => 1, :a => :a}.transform_keys{ |key| key.to_s.upcase } +# => {"" => nil, "A" => :a, "1" => 1} +</ruby> + +The result in case of collision is undefined: + +<ruby> +{"a" => 1, :a => 2}.transform_keys{ |key| key.to_s.upcase } +# => {"A" => 2}, in my test, can't rely on this result though +</ruby> + +This method may be useful for example to build specialized conversions. For instance +stringify_keys+ and +symbolize_keys+ use +transform_keys+ to perform their key conversions: + +<ruby> +def stringify_keys + transform_keys{ |key| key.to_s } +end +... +def symbolize_keys + transform_keys{ |key| key.to_sym rescue key } +end +</ruby> + +There's also the bang variant +transform_keys!+ that applies the block operations to keys in the very receiver. + +Besides that, one can use +deep_transform_keys+ and +deep_transform_keys!+ to perform the block operation on all the keys in the given hash and all the hashes nested into it. An example of the result is: + +<ruby> +{nil => nil, 1 => 1, :nested => {:a => 3, 5 => 5}}.deep_transform_keys{ |key| key.to_s.upcase } +# => {""=>nil, "1"=>1, "NESTED"=>{"A"=>3, "5"=>5}} +</ruby> + +NOTE: Defined in +active_support/core_ext/hash/keys.rb+. + h5. +stringify_keys+ and +stringify_keys!+ The method +stringify_keys+ returns a hash that has a stringified version of the keys in the receiver. It does so by sending +to_s+ to them: @@ -2579,6 +2688,13 @@ The second line can safely access the "type" key, and let the user to pass eithe There's also the bang variant +stringify_keys!+ that stringifies keys in the very receiver. +Besides that, one can use +deep_stringify_keys+ and +deep_stringify_keys!+ to stringify all the keys in the given hash and all the hashes nested into it. An example of the result is: + +<ruby> +{nil => nil, 1 => 1, :nested => {:a => 3, 5 => 5}}.deep_stringify_keys +# => {""=>nil, "1"=>1, "nested"=>{"a"=>3, "5"=>5}} +</ruby> + NOTE: Defined in +active_support/core_ext/hash/keys.rb+. h5. +symbolize_keys+ and +symbolize_keys!+ @@ -2613,6 +2729,13 @@ The second line can safely access the +:params+ key, and let the user to pass ei There's also the bang variant +symbolize_keys!+ that symbolizes keys in the very receiver. +Besides that, one can use +deep_symbolize_keys+ and +deep_symbolize_keys!+ to symbolize all the keys in the given hash and all the hashes nested into it. An example of the result is: + +<ruby> +{nil => nil, 1 => 1, "nested" => {"a" => 3, 5 => 5}}.deep_symbolize_keys +# => {nil=>nil, 1=>1, :nested=>{:a=>3, 5=>5}} +</ruby> + NOTE: Defined in +active_support/core_ext/hash/keys.rb+. h5. +to_options+ and +to_options!+ @@ -2869,8 +2992,6 @@ d.prev_year # => Sun, 28 Feb 1999 d.next_year # => Wed, 28 Feb 2001 </ruby> -Active Support defines these methods as well for Ruby 1.8. - +prev_year+ is aliased to +last_year+. h6. +prev_month+, +next_month+ @@ -2892,8 +3013,6 @@ Date.new(2000, 5, 31).next_month # => Fri, 30 Jun 2000 Date.new(2000, 1, 31).next_month # => Tue, 29 Feb 2000 </ruby> -Active Support defines these methods as well for Ruby 1.8. - +prev_month+ is aliased to +last_month+. h6. +beginning_of_week+, +end_of_week+ diff --git a/guides/source/asset_pipeline.textile b/guides/source/asset_pipeline.textile index 116a0a371a..105efe229e 100644 --- a/guides/source/asset_pipeline.textile +++ b/guides/source/asset_pipeline.textile @@ -545,7 +545,9 @@ config.assets.initialize_on_precompile = false The +prefix+ change makes Rails use a different URL for serving assets in development mode, and pass all requests to Sprockets. The prefix is still set to +/assets+ in the production environment. Without this change, the application would serve the precompiled assets from +public/assets+ in development, and you would not see any local changes until you compile assets again. -The +initialize_on_precompile+ change tell the precompile task to run without invoking Rails. You will also need to ensure that any compressors or minifiers are available on your development system. +The +initialize_on_precompile+ change tells the precompile task to run without invoking Rails. This is because the precompile task runs in production mode by default, and will attempt to connect to your specified production database. Please note that you cannot have code in pipeline files that relies on Rails resources (such as the database) when compiling locally with this option. + +You will also need to ensure that any compressors or minifiers are available on your development system. In practice, this will allow you to precompile locally, have those files in your working tree, and commit those files to source control when needed. Development mode will work as expected. diff --git a/guides/source/configuring.textile b/guides/source/configuring.textile index f114075cae..af46538bf5 100644 --- a/guides/source/configuring.textile +++ b/guides/source/configuring.textile @@ -585,7 +585,7 @@ After loading the framework and any gems in your application, Rails turns to loa NOTE: You can use subfolders to organize your initializers if you like, because Rails will look into the whole file hierarchy from the initializers folder on down. -TIP: If you have any ordering dependency in your initializers, you can control the load order by naming. For example, +01_critical.rb+ will be loaded before +02_normal.rb+. +TIP: If you have any ordering dependency in your initializers, you can control the load order through naming. Initializer files are loaded in alphabetical order by their path. For example, +01_critical.rb+ will be loaded before +02_normal.rb+. h3. Initialization events diff --git a/guides/source/contributing_to_ruby_on_rails.textile b/guides/source/contributing_to_ruby_on_rails.textile index df475a2359..72cdea885f 100644 --- a/guides/source/contributing_to_ruby_on_rails.textile +++ b/guides/source/contributing_to_ruby_on_rails.textile @@ -343,9 +343,39 @@ h4. Commit Your Changes When you're happy with the code on your computer, you need to commit the changes to git: <shell> -$ git commit -a -m "Here is a commit message on what I changed in this commit" +$ git commit -a </shell> +At this point, your editor should be fired up and you can write a message for this commit. Well formatted and descriptive commit messages are extremely helpful for the others, especially when figuring out why given change was made, so please take the time to write it. + +Good commit message should be formatted according to the following example: + +<plain> +Short summary (ideally 50 characters or less) + +More detailed description, if necessary. It should be wrapped to 72 +characters. Try to be as descriptive as you can, even if you think that +the commit content is obvious, it may not be obvious to others. You +should add such description also if it's already present in bug tracker, +it should not be necessary to visit a webpage to check the history. + +Description can have multiple paragraps and you can use code examples +inside, just indent it with 4 spaces: + + class PostsController + def index + respond_with Post.limit(10) + end + end + +You can also add bullet points: + +- you can use dashes or asterisks + +- also, try to indent next line of a point for readability, if it's too + long to fit in 72 characters +</plain> + TIP. Please squash your commits into a single commit when appropriate. This simplifies future cherry picks, and also keeps the git log clean. h4. Update Master @@ -400,6 +430,35 @@ h4. Iterate as Necessary It’s entirely possible that the feedback you get will suggest changes. Don’t get discouraged: the whole point of contributing to an active open source project is to tap into community knowledge. If people are encouraging you to tweak your code, then it’s worth making the tweaks and resubmitting. If the feedback is that your code doesn’t belong in the core, you might still think about releasing it as a gem. +h4. Backporting + +Changes that are merged into master are intended for the next major release of Rails. Sometimes, it might be beneficial for your changes to propagate back to the maintenance releases for older stable branches. Generally, security fixes and bug fixes are good candidates for a backport, while new features and patches that introduce a change in behavior will not be accepted. When in doubt, it is best to consult a rails team member before backporting your changes to avoid wasted effort. + +For simple fixes, the easiest way to backport your change is to "extract a diff from your changes in master and apply them to the target branch":http://ariejan.net/2009/10/26/how-to-create-and-apply-a-patch-with-git. + +First make sure your changes are the only difference between your current branch and master: + +<shell> +$ git log master..HEAD +</shell> + +Then extract the diff: + +<shell> +$ git format-patch master --stdout > ~/my_changes.patch +</shell> + +Switch over to the target branch and apply your changes: + +<shell> +$ git checkout -b my_backport_branch 3-2-stable +$ git apply ~/my_changes.patch +</shell> + +This works well for simple changes. However, if your changes are complicated or if the code in master has deviated significantly from your target branch, it might require more work on your part. The difficulty of a backport varies greatly from case to case, and sometimes it is simply not worth the effort. + +Once you have resolved all conflicts and made sure all the tests are passing, push your changes and open a separate pull request for your backport. It is also worth noting that older branches might have a different set of build targets than master. When possible, it is best to first test your backport locally against the ruby versions listed in +.travis.yml+ before submitting your pull request. + And then ... think about your next contribution! h3. Rails Contributors diff --git a/guides/source/credits.html.erb b/guides/source/credits.html.erb index da6bd6acdf..04deec6a11 100644 --- a/guides/source/credits.html.erb +++ b/guides/source/credits.html.erb @@ -31,6 +31,10 @@ Ruby on Rails Guides: Credits Ryan Bigg works as a consultant at <a href="http://rubyx.com">RubyX</a> and has been working with Rails since 2006. He's co-authoring a book called <a href="http://manning.com/katz">Rails 3 in Action</a> and he's written many gems which can be seen on <a href="http://github.com/radar">his GitHub page</a> and he also tweets prolifically as <a href="http://twitter.com/ryanbigg">@ryanbigg</a>. <% end %> +<%= author('Oscar Del Ben', 'oscardelben', 'oscardelben.jpg') do %> +Oscar Del Ben is a software engineer at <a href="http://www.wildfireapp.com/">Wildfire</a>. He's a regular open source contributor (<a href="https://github.com/oscardelben">Github account</a>) and tweets regularly at <a href="https://twitter.com/oscardelben">@oscardelben</a>. + <% end %> + <%= author('Frederick Cheung', 'fcheung') do %> Frederick Cheung is Chief Wizard at Texperts where he has been using Rails since 2006. He is based in Cambridge (UK) and when not consuming fine ales he blogs at <a href="http://www.spacevatican.org">spacevatican.org</a>. <% end %> diff --git a/guides/source/debugging_rails_applications.textile b/guides/source/debugging_rails_applications.textile index 45fa4ada78..0802a2db26 100644 --- a/guides/source/debugging_rails_applications.textile +++ b/guides/source/debugging_rails_applications.textile @@ -698,7 +698,7 @@ There are some Rails plugins to help you to find errors and debug your applicati h3. References -* "ruby-debug Homepage":http://www.datanoise.com/ruby-debug +* "ruby-debug Homepage":http://bashdb.sourceforge.net/ruby-debug/home-page.html * "debugger Homepage":http://github.com/cldwalker/debugger * "Article: Debugging a Rails application with ruby-debug":http://www.sitepoint.com/article/debug-rails-app-ruby-debug/ * "ruby-debug Basics screencast":http://brian.maybeyoureinsane.net/blog/2007/05/07/ruby-debug-basics-screencast/ diff --git a/guides/source/engines.textile b/guides/source/engines.textile index 880be57fb5..c35305a822 100644 --- a/guides/source/engines.textile +++ b/guides/source/engines.textile @@ -738,7 +738,7 @@ This tells sprockets to add you engine assets when +rake assets:precompile+ is r You can define assets for precompilation in +engine.rb+ <ruby> -initializer do |app| +initializer "blorgh.assets.precompile" do |app| app.config.assets.precompile += %w(admin.css admin.js) end </ruby> diff --git a/guides/source/form_helpers.textile b/guides/source/form_helpers.textile index 711ed3d859..8106de6f9d 100644 --- a/guides/source/form_helpers.textile +++ b/guides/source/form_helpers.textile @@ -150,7 +150,7 @@ NOTE: Always use labels for checkbox and radio buttons. They associate text with h4. Other Helpers of Interest -Other form controls worth mentioning are textareas, password fields, hidden fields, search fields, telephone fields, date fields, URL fields and email fields: +Other form controls worth mentioning are textareas, password fields, hidden fields, search fields, telephone fields, date fields, time fields, color fields, datetime fields, datetime-local fields, month fields, week fields, URL fields and email fields: <erb> <%= text_area_tag(:message, "Hi, nice site", :size => "24x6") %> @@ -159,8 +159,14 @@ Other form controls worth mentioning are textareas, password fields, hidden fiel <%= search_field(:user, :name) %> <%= telephone_field(:user, :phone) %> <%= date_field(:user, :born_on) %> +<%= datetime_field(:user, :meeting_time) %> +<%= datetime_local_field(:user, :graduation_day) %> +<%= month_field(:user, :birthday_month) %> +<%= week_field(:user, :birthday_week) %> <%= url_field(:user, :homepage) %> <%= email_field(:user, :address) %> +<%= color_field(:user, :favorite_color) %> +<%= time_field(:task, :started_at) %> </erb> Output: @@ -172,13 +178,19 @@ Output: <input id="user_name" name="user[name]" type="search" /> <input id="user_phone" name="user[phone]" type="tel" /> <input id="user_born_on" name="user[born_on]" type="date" /> +<input id="user_meeting_time" name="user[meeting_time]" type="datetime" /> +<input id="user_graduation_day" name="user[graduation_day]" type="datetime-local" /> +<input id="user_birthday_month" name="user[birthday_month]" type="month" /> +<input id="user_birthday_week" name="user[birthday_week]" type="week" /> <input id="user_homepage" name="user[homepage]" type="url" /> <input id="user_address" name="user[address]" type="email" /> +<input id="user_favorite_color" name="user[favorite_color]" type="color" value="#000000" /> +<input id="task_started_at" name="task[started_at]" type="time" /> </html> Hidden inputs are not shown to the user but instead hold data like any textual input. Values inside them can be changed with JavaScript. -IMPORTANT: The search, telephone, date, URL, and email inputs are HTML5 controls. If you require your app to have a consistent experience in older browsers, you will need an HTML5 polyfill (provided by CSS and/or JavaScript). There is definitely "no shortage of solutions for this":https://github.com/Modernizr/Modernizr/wiki/HTML5-Cross-Browser-Polyfills, although a couple of popular tools at the moment are "Modernizr":http://www.modernizr.com/ and "yepnope":http://yepnopejs.com/, which provide a simple way to add functionality based on the presence of detected HTML5 features. +IMPORTANT: The search, telephone, date, time, color, datetime, datetime-local, month, week, URL, and email inputs are HTML5 controls. If you require your app to have a consistent experience in older browsers, you will need an HTML5 polyfill (provided by CSS and/or JavaScript). There is definitely "no shortage of solutions for this":https://github.com/Modernizr/Modernizr/wiki/HTML5-Cross-Browser-Polyfills, although a couple of popular tools at the moment are "Modernizr":http://www.modernizr.com/ and "yepnope":http://yepnopejs.com/, which provide a simple way to add functionality based on the presence of detected HTML5 features. TIP: If you're using password input fields (for any purpose), you might want to configure your application to prevent those parameters from being logged. You can learn about this in the "Security Guide":security.html#logging. @@ -471,7 +483,7 @@ Rails _used_ to have a +country_select+ helper for choosing countries, but this h3. Using Date and Time Form Helpers -You can choose not to use the form helpers generating HTML5 date input fields and use the alternative date and time helpers. These date and time helpers differ from all the other form helpers in two important respects: +You can choose not to use the form helpers generating HTML5 date and time input fields and use the alternative date and time helpers. These date and time helpers differ from all the other form helpers in two important respects: # Dates and times are not representable by a single input element. Instead you have several, one for each component (year, month, day etc.) and so there is no single value in your +params+ hash with your date or time. # Other helpers use the +_tag+ suffix to indicate whether a helper is a barebones helper or one that operates on model objects. With dates and times, +select_date+, +select_time+ and +select_datetime+ are the barebones helpers, +date_select+, +time_select+ and +datetime_select+ are the equivalent model object helpers. diff --git a/guides/source/getting_started.textile b/guides/source/getting_started.textile index e93a94448a..f25e0c0200 100644 --- a/guides/source/getting_started.textile +++ b/guides/source/getting_started.textile @@ -13,8 +13,6 @@ endprologue. WARNING. This Guide is based on Rails 3.2. Some of the code shown here will not work in earlier versions of Rails. -WARNING: The Edge version of this guide is currently being re-worked. Please excuse us while we re-arrange the place. - h3. Guide Assumptions This guide is designed for beginners who want to get started with a Rails @@ -77,7 +75,7 @@ By following along with this guide, you'll create a Rails project called (very) simple weblog. Before you can start building the application, you need to make sure that you have Rails itself installed. -TIP: The examples below use # and $ to denote terminal prompts. If you are using Windows, your prompt will look something like c:\source_code> +TIP: The examples below use # and $ to denote superuser and regular user terminal prompts respectively in a UNIX-like OS. If you are using Windows, your prompt will look something like c:\source_code> h4. Installing Rails @@ -110,7 +108,7 @@ To use this generator, open a terminal, navigate to a directory where you have r $ rails new blog </shell> -This will create a Rails application called Blog in a directory called blog. +This will create a Rails application called Blog in a directory called blog and install the gem dependencies that are already mentioned in +Gemfile+ using +bundle install+. TIP: You can see all of the command line options that the Rails application builder accepts by running +rails new -h+. @@ -140,7 +138,7 @@ application. Most of the work in this tutorial will happen in the +app/+ folder, |README.rdoc|This is a brief instruction manual for your application. You should edit this file to tell others what your application does, how to set it up, and so on.| |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| +|tmp/|Temporary files (like cache, pid and session files)| |vendor/|A place for all third-party code. In a typical Rails application, this includes Ruby Gems and the Rails source code (if you optionally install it into your project).| h3. Hello, Rails! @@ -179,7 +177,28 @@ To create a new controller, you will need to run the "controller" generator and $ rails generate controller welcome index </shell> -Rails will create several files for you. Most important of these are of course the controller, located at +app/controllers/welcome_controller.rb+ and the view, located at +app/views/welcome/index.html.erb+. +Rails will create several files and a route for you. + +<shell> +create app/controllers/welcome_controller.rb + route get "welcome/index" +invoke erb +create app/views/welcome +create app/views/welcome/index.html.erb +invoke test_unit +create test/functional/welcome_controller_test.rb +invoke helper +create app/helpers/welcome_helper.rb +invoke test_unit +create test/unit/helpers/welcome_helper_test.rb +invoke assets +invoke coffee +create app/assets/javascripts/welcome.js.coffee +invoke scss +create app/assets/stylesheets/welcome.css.scss +</shell> + +Most important of these are of course the controller, located at +app/controllers/welcome_controller.rb+ and the view, located at +app/views/welcome/index.html.erb+. Open the +app/views/welcome/index.html.erb+ file in your text editor and edit it to contain a single line of code: @@ -197,18 +216,27 @@ You need to do this because Rails will serve any static file in the +public+ dir Next, you have to tell Rails where your actual home page is located. -Open the file +config/routes.rb+ in your editor. This is your application's _routing file_ which holds entries in a special DSL (domain-specific language) that tells Rails how to connect incoming requests to controllers and actions. This file contains many sample routes on commented lines, and one of them actually shows you how to connect the root of your site to a specific controller and action. Find the line beginning with +root :to+ and uncomment it. It should look something like the following: +Open the file +config/routes.rb+ in your editor. <ruby> Blog::Application.routes.draw do - - #... + get "welcome/index" + + # The priority is based upon order of creation: + # first created -> highest priority. + # ... # You can have the root of your site routed with "root" # just remember to delete public/index.html. - root :to => "welcome#index" + # root :to => "welcome#index" +</ruby> + +This is your application's _routing file_ which holds entries in a special DSL (domain-specific language) that tells Rails how to connect incoming requests to controllers and actions. This file contains many sample routes on commented lines, and one of them actually shows you how to connect the root of your site to a specific controller and action. Find the line beginning with +root :to+ and uncomment it. It should look something like the following: + +<ruby> +root :to => "welcome#index" </ruby> -The +root :to => "welcome#index"+ tells Rails to map requests to the root of the application to the welcome controller's index action. This was created earlier when you ran the controller generator (+rails generate controller welcome index+). +The +root :to => "welcome#index"+ tells Rails to map requests to the root of the application to the welcome controller's index action and +get "welcome/index"+ tells Rails to map requests to "http://localhost:3000/welcome/index":http://localhost:3000/welcome/index to the welcome controller's index action. This was created earlier when you ran the controller generator (+rails generate controller welcome index+). If you navigate to "http://localhost:3000":http://localhost:3000 in your browser, you'll see the +Hello, Rails!+ message you put into +app/views/welcome/index.html.erb+, indicating that this new route is indeed going to +WelcomeController+'s +index+ action and is rendering the view correctly. @@ -502,7 +530,7 @@ database columns. In the first line we do just that (remember that +params[:post]+ contains the attributes we're interested in). Then, +@post.save+ is responsible for saving the model in the database. Finally, we redirect the user to the +show+ action, -wich we'll define later. +which we'll define later. TIP: As we'll see later, +@post.save+ returns a boolean indicating wherever the model was saved or not. @@ -560,19 +588,21 @@ be able to create a post. Try it! h4. Listing all posts We still need a way to list all our posts, so let's do that. As usual, -we'll need a route, a controller action, and a view: +we'll need a route placed into +config/routes.rb+: <ruby> -# Add to config/routes.rb get "posts" => "posts#index" +</ruby> + +And an action for that route inside the +PostsController+ in the +app/controllers/posts_controller.rb+ file: -# Add to app/controllers/posts_controller.rb +<ruby> def index @posts = Post.all end </ruby> -+app/view/posts/index.html.erb+: +And then finally a view for this action, located at +app/views/posts/index.html.erb+: <erb> <h1>Listing posts</h1> @@ -583,15 +613,17 @@ end <th>Text</th> </tr> -<% @posts.each do |post| %> - <tr> - <td><%= post.title %></td> - <td><%= post.text %></td> - </tr> -<% end %> + <% @posts.each do |post| %> + <tr> + <td><%= post.title %></td> + <td><%= post.text %></td> + </tr> + <% end %> </table> </erb> +Now if you go to +http://localhost:3000/posts+ you will see a list of all the posts that you have created. + h4. Adding links You can now create, show, and list posts. Now let's add some links to @@ -608,41 +640,25 @@ The +link_to+ method is one of Rails' built-in view helpers. It creates a hyperlink based on text to display and where to go - in this case, to the path for posts. -Let's add links to the other views as well. +Let's add links to the other views as well, starting with adding this "New Post" link to +app/views/posts/index.html.erb+, placing it above the +<table>+ tag: <erb> -# app/views/posts/index.html.erb - -<h1>Listing posts</h1> - <%= link_to 'New post', :action => :new %> +</erb> -<table> - <tr> - <th>Title</th> - <th>Text</th> - <th></th> - </tr> - -<% @posts.each do |post| %> - <tr> - <td><%= post.title %></td> - <td><%= post.text %></td> - <td><%= link_to 'Show', :action => :show, :id => post.id %></td> - </tr> -<% end %> -</table> - -# app/views/posts/new.html.erb +This link will allow you to bring up the form that lets you create a new post. You should also add a link to this template -- +app/views/posts/new.html.erb+ -- to go back to the +index+ action. Do this by adding this underneath the form in this template: +<erb> <%= form_for :post do |f| %> ... <% end %> <%= link_to 'Back', :action => :index %> +</erb> -# app/views/posts/show.html.erb +Finally, add another link to the +app/views/posts/show.html.erb+ template to go back to the +index+ action as well, so that people who are viewing a single post can go back and view the whole list again: +<erb> <p> <strong>Title:</strong> <%= @post.title %> @@ -664,7 +680,7 @@ TIP: In development mode (which is what you're working in by default), Rails reloads your application with every browser request, so there's no need to stop and restart the web server when a change is made. -h4. Adding Some Validation +h4. Allowing the update of fields The model file, +app/models/post.rb+ is about as simple as it can get: @@ -679,11 +695,28 @@ your Rails models for free, including basic database CRUD (Create, Read, Update, Destroy) operations, data validation, as well as sophisticated search support and the ability to relate multiple models to one another. +Rails includes methods to help you secure some of your model fields. +Open the +app/models/post.rb+ file and edit it: + +<ruby> +class Post < ActiveRecord::Base + attr_accessible :text, :title +end +</ruby> + +This change will ensure that all changes made through HTML forms can edit the content of the text and title fields. +It will not be possible to define any other field value through forms. You can still define them by calling the `field=` method of course. +Accessible attributes and the mass assignment problem is covered in details in the "Security guide":security.html#mass-assignment + +h4. Adding Some Validation + Rails includes methods to help you validate the data that you send to models. Open the +app/models/post.rb+ file and edit it: <ruby> class Post < ActiveRecord::Base + attr_accessible :text, :title + validates :title, :presence => true, :length => { :minimum => 5 } end @@ -695,9 +728,12 @@ format, and the existence of associated objects. Validations are covered in deta in "Active Record Validations and Callbacks":active_record_validations_callbacks.html#validations-overview -If you open +posts_controller+ again, you'll notice that we don't check -the result of calling +@post.save+. We need to change its behavior to -show the form back to the user if any error occur: +With the validation now in place, when you call +@post.save+ on an invalid +post, it will return +false+. If you open +app/controllers/posts_controller.rb+ +again, you'll notice that we don't check the result of calling +@post.save+ +inside the +create+ action. If +@post.save+ fails in this situation, we need to +show the form back to the user. To do this, change the +new+ and +create+ +actions inside +app/controllers/posts_controller.rb+ to these: <ruby> def new @@ -715,13 +751,11 @@ def create end </ruby> -Notice that I've also added +@post = Post.new+ to the +new+ action. I'll -explain why I did that in the next section, for now add that to your -controller as well. +The +new+ action is now creating a new instance variable called +@post+, and +you'll see why that is in just a few moments. -Also notice that we use +render+ instead of +redirect_to+ when +save+ -returns false. We can use +render+ so that the +@post+ object is passed -back to the view. +Notice that inside the +create+ action we use +render+ instead of +redirect_to+ when +save+ +returns +false+. The +render+ method is used so that the +@post+ object is passed back to the +new+ template when it is rendered. This rendering is done within the same request as the form submission, whereas the +redirect_to+ will tell the browser to issue another request. If you reload "http://localhost:3000/posts/new":http://localhost:3000/posts/new and @@ -765,9 +799,8 @@ A few things are going on. We check if there are any errors with +@post.errors.any?+, and in that case we show a list of all errors with +@post.errors.full_messages+. -+pluralize+ is a rails helper -that takes a number and a string as its arguments. If the number is -greater than one, the string will be automatically pluralized. ++pluralize+ is a rails helper that takes a number and a string as its +arguments. If the number is greater than one, the string will be automatically pluralized. The reason why we added +@post = Post.new+ in +posts_controller+ is that otherwise +@post+ would be +nil+ in our view, and calling @@ -777,7 +810,8 @@ TIP: Rails automatically wraps fields that contain an error with a div with class +field_with_errors+. You can define a css rule to make them standout. -Now you'll get a nice error message when saving a post without title: +Now you'll get a nice error message when saving a post without title when you +attempt to do just that on the "new post form(http://localhost:3000/posts/new)":http://localhost:3000/posts/new. !images/getting_started/form_with_errors.png(Form With Errors)! @@ -841,21 +875,23 @@ it look as follows: <%= link_to 'Back', :action => :index %> </erb> -This time we point the form to the +update+ action (not defined yet). +This time we point the form to the +update+ action, which is not defined yet +but will be very soon. + The +:method => :put+ option tells Rails that we want this form to be -submitted via +put+, which is the http method you're expected to use to +submitted via the +PUT+, HTTP method which is the HTTP method you're expected to use to *update* resources according to the REST protocol. TIP: By default forms built with the +form_for_ helper are sent via +POST+. -Moving on, we need to add the +update+ action. The file +Next, we need to add the +update+ action. The file +config/routes.rb+ will need just one more line: <ruby> put "posts/:id" => "posts#update" </ruby> -And the +update+ action in +posts_controller+ itself should not look too complicated by now: +And then create the +update+ action in +app/controllers/posts_controller.rb+: <ruby> def update @@ -869,7 +905,7 @@ def update end </ruby> -The new method +update_attributes+ is used when you want to update a record +The new method, +update_attributes+, is used when you want to update a record that already exists, and it accepts an hash containing the attributes that you want to update. As before, if there was an error updating the post we want to show the form back to the user. @@ -879,11 +915,11 @@ example, if you'd call +@post.update_attributes(:title => 'A new title')+ Rails would only update the +title+ attribute, leaving all other attributes untouched. -Finally, we want to show a link to the +edit+ action in the +index+ and -+show+ views: +Finally, we want to show a link to the +edit+ action in the list of all the +posts, so let's add that now to +app/views/posts/index.html.erb+ to make it +appear next to the "Show" link: <erb> -# app/view/posts/index.html.erb <table> <tr> @@ -902,11 +938,16 @@ Finally, we want to show a link to the +edit+ action in the +index+ and </tr> <% end %> </table> +</erb> -# app/view/posts/show.html.erb +And we'll also add one to the +app/views/posts/show.html.erb+ template as well, +so that there's also an "Edit" link on a post's page. Add this at the bottom of +the template: +<erb> ... + <%= link_to 'Back', :action => :index %> | <%= link_to 'Edit', :action => :edit, :id => @post.id %> </erb> @@ -935,8 +976,8 @@ simple example: <%= @user.about_me %> </erb> -The +show+ view will automatically include the content of the -+_user_details+ view. Note that partials are prefixed by an underscore, +The +users/show+ template will automatically include the content of the ++users/_user_details+ template. Note that partials are prefixed by an underscore, as to not be confused with regular views. However, you don't include the underscore when including them with the +helper+ method. @@ -945,7 +986,7 @@ Rails":layouts_and_rendering.html guide. Our +edit+ action looks very similar to the +new+ action, in fact they both share the same code for displaying the form. Lets clean them up by -using a +_form+ partial. +using a partial. Create a new file +app/views/posts/_form.html.erb+ with the following content: @@ -955,7 +996,7 @@ content: <% if @post.errors.any? %> <div id="errorExplanation"> <h2><%= pluralize(@post.errors.count, "error") %> prohibited - this post from being saved:</h2> + this post from being saved:</h2> <ul> <% @post.errors.full_messages.each do |msg| %> <li><%= msg %></li> @@ -979,23 +1020,23 @@ content: <% end %> </erb> -Everything except for the +form_for+ declaration remained the same. I'll -explain later how +form_for+ can figure out the right +action+ and -+method+ attributes when building the form, for now let's update the -+new+ and +edit+ views: +Everything except for the +form_for+ declaration remained the same. +How +form_for+ can figure out the right +action+ and +method+ attributes +when building the form will be explained in just a moment. For now, let's update the ++app/views/posts/new.html.erb+ view to use this new partial, rewriting it +completely: <erb> -# app/views/posts/new.html.erb - <h1>New post</h1> <%= render 'form' %> <%= link_to 'Back', :action => :index %> +</erb> +Then do the same for the +app/views/posts/edit.html.erb+ view: -# app/views/posts/edit.html.erb - +<erb> <h1>Edit post</h1> <%= render 'form' %> @@ -1003,8 +1044,7 @@ explain later how +form_for+ can figure out the right +action+ and <%= link_to 'Back', :action => :index %> </erb> -Point your browser to -"http://localhost:3000/posts/new":http://localhost:3000/posts/new and +Point your browser to "http://localhost:3000/posts/new":http://localhost:3000/posts/new and try creating a new post. Everything still works. Now try editing the post and you'll receive the following error: @@ -1022,7 +1062,8 @@ knows that it should create new objects via POST and update them via PUT. If you run +rake routes+ from the console you'll see that we already -have a +posts_path+ route, which was created automatically by Rails. +have a +posts_path+ route, which was created automatically by Rails when we +defined the route for the index action. However, we don't have a +post_path+ yet, which is the reason why we received an error before. @@ -1045,26 +1086,37 @@ line like this: get "posts/:id" => "posts#show", :as => :post </ruby> -Now you'll be able to update posts again. +The +:as+ option tells the +get+ method that we want to make routing helpers +called +post_url+ and +post_path+ available to our application. These are +precisely the methods that the +form_for+ needs when editing a post, and so now +you'll be able to update posts again. + +NOTE: The +:as+ option is available on the +post+, +put+, +delete+ and +match+ +routing methods also. h4. Deleting Posts We're now ready to cover the "D" part of CRUD, deleting posts from the database. Following the REST convention, we're going to add a route for -deleting posts: +deleting posts to +config/routes.rb+: <ruby> -# config/routes.rb - delete "posts/:id" => "posts#destroy" </ruby> -We use the +delete+ method for destroying resources, which is mapped to -the +destroy+ action, which is provided below: +The +delete+ routing method should be used for routes that destroy +resources. If this was left as a typical +get+ route, it could be possible for +people to craft malicious URLs like this: -<ruby> -# app/controllers/posts_controller.rb +<html> +<a href='http://yoursite.com/posts/1/destroy'>look at this cat!</a> +</html> + +We use the +delete+ method for destroying resources, and this route is mapped to +the +destroy+ action inside +app/controllers/posts_controller.rb+, which doesn't exist yet, but is +provided below: +<ruby> def destroy @post = Post.find(params[:id]) @post.destroy @@ -1074,13 +1126,15 @@ end </ruby> You can call +destroy+ on Active Record objects when you want to delete -them from the dabase. Note that we don't need to add a view for this +them from the database. Note that we don't need to add a view for this action since we're redirecting to the +index+ action. -Finally, add a 'destroy' link to your +index+ action to wrap everything +Finally, add a 'destroy' link to your +index+ action template +(+app/views/posts/index.html.erb) to wrap everything together. <erb> +<h1>Listing Posts</h1> <table> <tr> <th>Title</th> @@ -1103,11 +1157,14 @@ together. </erb> Here we're using +link_to+ in a different way. We wrap the -+:action+ and +:id+ attributes in a hash so that we can pass other -arguments to +link_to+. The +:method+ and +:confirm+ -options are used as html5 attributes so that when the click is linked, ++:action+ and +:id+ attributes in a hash so that we can pass those two keys in +first as one argument, and then the final two keys as another argument. The +:method+ and +:confirm+ +options are used as HTML5 attributes so that when the link is clicked, Rails will first show a confirm dialog to the user, and then submit the -link with method +delete+. This is done via javascript automatically. +link with method +delete+. This is done via the JavaScript file +jquery_ujs+ +which is automatically included into your application's layout +(+app/views/layouts/application.html.erb+) when you generated the application. +Without this file, the confirmation dialog box wouldn't appear. !images/getting_started/confirm_dialog.png(Confirm Dialog)! @@ -1147,7 +1204,7 @@ end </ruby> If you run +rake routes+, you'll see that all the routes that we -declared before are still available, and the app still works as before. +declared before are still available: <shell> # rake routes @@ -1161,18 +1218,22 @@ edit_post GET /posts/:id/edit(.:format) posts#edit root / welcome#index </shell> +Also, if you go through the motions of creating, updating and deleting +posts the app still works as before. + TIP: In general, Rails encourages the use of resources objects in place -of declaring routes manually. For more information about routing, see +of declaring routes manually. It was only done in this guide as a learning +exercise. For more information about routing, see "Rails Routing from the Outside In":routing.html. h3. Adding a Second Model It's time to add a second model to the application. The second model will handle comments on -blog posts. +posts. h4. Generating a Model -We're going to se the same generator that we used before when creating +We're going to see the same generator that we used before when creating the +Post+ model. This time we'll create a +Comment+ model to hold reference of post comments. Run this command in your terminal: @@ -1332,7 +1393,7 @@ So first, we'll wire up the Post show template <p> <strong>Text:</strong> - <%= @post.texthttp://beginningruby.org/ %> + <%= @post.text %> </p> <h2>Add a comment:</h2> @@ -1355,7 +1416,10 @@ So first, we'll wire up the Post show template </erb> This adds a form on the +Post+ show page that creates a new comment by -calling the +CommentsController+ +create+ action. Let's wire that up: +calling the +CommentsController+ +create+ action. The +form_for+ call here uses +an array, which will build a nested route, such as +/posts/1/comments+. + +Let's wire up the +create+: <ruby> class CommentsController < ApplicationController @@ -1391,7 +1455,7 @@ template. This is where we want the comment to show, so let's add that to the <p> <strong>Text:</strong> - <%= @post.texthttp://beginningruby.org/ %> + <%= @post.text %> </p> <h2>Comments</h2> @@ -1439,7 +1503,7 @@ use partials to clean it up. h4. Rendering Partial Collections -First we will make a comment partial to extract showing all the comments for the +First, we will make a comment partial to extract showing all the comments for the post. Create the file +app/views/comments/_comment.html.erb+ and put the following into it: @@ -1466,7 +1530,7 @@ following: <p> <strong>Text:</strong> - <%= @post.texthttp://beginningruby.org/ %> + <%= @post.text %> </p> <h2>Comments</h2> @@ -1528,7 +1592,7 @@ Then you make the +app/views/posts/show.html.erb+ look like the following: <p> <strong>Text:</strong> - <%= @post.texthttp://beginningruby.org/ %> + <%= @post.text %> </p> <h2>Add a comment:</h2> diff --git a/guides/source/initialization.textile b/guides/source/initialization.textile index 155a439e64..48d4373afe 100644 --- a/guides/source/initialization.textile +++ b/guides/source/initialization.textile @@ -1,13 +1,15 @@ h2. The Rails Initialization Process -This guide explains the internals of the initialization process in Rails as of Rails 3.1. It is an extremely in-depth guide and recommended for advanced Rails developers. +This guide explains the internals of the initialization process in Rails +as of Rails 4. It is an extremely in-depth guide and recommended for advanced Rails developers. * Using +rails server+ * Using Passenger endprologue. -This guide goes through every single file, class and method call that is required to boot up the Ruby on Rails stack for a default Rails 3.1 application, explaining each part in detail along the way. For this guide, we will be focusing on how the two most common methods (+rails server+ and Passenger) boot a Rails application. +This guide goes through every single file, class and method call that is +required to boot up the Ruby on Rails stack for a default Rails 4 application, explaining each part in detail along the way. For this guide, we will be focusing on how the two most common methods (+rails server+ and Passenger) boot a Rails application. NOTE: Paths in this guide are relative to Rails or a Rails application unless otherwise specified. @@ -22,16 +24,15 @@ The actual +rails+ command is kept in _bin/rails_: <ruby> #!/usr/bin/env ruby -begin - require "rails/cli" -rescue LoadError - railties_path = File.expand_path('../../railties/lib', __FILE__) +if File.exists?(File.join(File.expand_path('../../..', __FILE__), '.git')) + railties_path = File.expand_path('../../lib', __FILE__) $:.unshift(railties_path) - require "rails/cli" end +require "rails/cli" </ruby> -This file will attempt to load +rails/cli+. If it cannot find it then +railties/lib+ is added to the load path (+$:+) before retrying. +This file will first attempt to push the +railties/lib+ directory if +present, and then require +rails/cli+. h4. +railties/lib/rails/cli.rb+ @@ -46,7 +47,7 @@ require 'rails/script_rails_loader' Rails::ScriptRailsLoader.exec_script_rails! require 'rails/ruby_version_check' -Signal.trap("INT") { puts; exit } +Signal.trap("INT") { puts; exit(1) } if ARGV.first == 'plugin' ARGV.shift @@ -120,6 +121,9 @@ exec RUBY, SCRIPT_RAILS, *ARGV if in_rails_application? This is effectively the same as running +ruby script/rails [arguments]+, where +[arguments]+ at this point in time is simply "server". +TIP: If you execute +script/rails+ directly from your Rails app you will +avoid executing the code that we just described. + h4. +script/rails+ This file is as follows: @@ -134,30 +138,30 @@ The +APP_PATH+ constant will be used later in +rails/commands+. The +config/boot h4. +config/boot.rb+ -+config/boot.rb+ contains this: ++config/boot.rb+ contains: <ruby> # Set up gems listed in the Gemfile. -gemfile = File.expand_path('../../Gemfile', __FILE__) -begin - ENV['BUNDLE_GEMFILE'] = gemfile - require 'bundler' - Bundler.setup -rescue Bundler::GemNotFound => e - STDERR.puts e.message - STDERR.puts "Try running `bundle install`." - exit! -end if File.exist?(gemfile) +ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', __FILE__) + +require 'bundler/setup' if File.exists?(ENV['BUNDLE_GEMFILE']) </ruby> -In a standard Rails application, there's a +Gemfile+ which declares all dependencies of the application. +config/boot.rb+ sets +ENV["BUNDLE_GEMFILE"]+ to the location of this file, then requires Bundler and calls +Bundler.setup+ which adds the dependencies of the application (including all the Rails parts) to the load path, making them available for the application to load. The gems that a Rails 3.1 application depends on are as follows: +In a standard Rails application, there's a +Gemfile+ which declares all +dependencies of the application. +config/boot.rb+ sets ++ENV['BUNDLE_GEMFILE']+ to the location of this file. If the Gemfile +exists, +bundler/setup+ is then required. + +The gems that a Rails 4 application depends on are as follows: + +TODO: change these when the Rails 4 release is near. * abstract (1.0.0) -* actionmailer (3.1.0.beta) -* actionpack (3.1.0.beta) -* activemodel (3.1.0.beta) -* activerecord (3.1.0.beta) -* activesupport (3.1.0.beta) +* actionmailer (4.0.0.beta) +* actionpack (4.0.0.beta) +* activemodel (4.0.0.beta) +* activerecord (4.0.0.beta) +* activesupport (4.0.0.beta) * arel (2.0.7) * builder (3.0.0) * bundler (1.0.6) @@ -170,8 +174,8 @@ In a standard Rails application, there's a +Gemfile+ which declares all dependen * rack-cache (0.5.3) * rack-mount (0.6.13) * rack-test (0.5.6) -* rails (3.1.0.beta) -* railties (3.1.0.beta) +* rails (4.0.0.beta) +* railties (4.0.0.beta) * rake (0.8.7) * sqlite3-ruby (1.3.2) * thor (0.14.6) @@ -183,8 +187,11 @@ h4. +rails/commands.rb+ Once +config/boot.rb+ has finished, the next file that is required is +rails/commands+ which will execute a command based on the arguments passed in. In this case, the +ARGV+ array simply contains +server+ which is extracted into the +command+ variable using these lines: <ruby> +ARGV << '--help' if ARGV.empty? + aliases = { "g" => "generate", + "d" => "destroy", "c" => "console", "s" => "server", "db" => "dbconsole", @@ -195,6 +202,9 @@ command = ARGV.shift command = aliases[command] || command </ruby> +TIP: As you can see, an empty ARGV list will make Rails show the help +snippet. + If we used <tt>s</tt> rather than +server+, Rails will use the +aliases+ defined in the file and match them to their respective commands. With the +server+ command, Rails will run this code: <ruby> @@ -361,8 +371,9 @@ This method is defined like this: <ruby> def start + url = "#{options[:SSLEnable] ? 'https' : 'http'}://#{options[:Host]}:#{options[:Port]}" puts "=> Booting #{ActiveSupport::Inflector.demodulize(server)}" - puts "=> Rails #{Rails.version} application starting in #{Rails.env} on http://#{options[:Host]}:#{options[:Port]}" + puts "=> Rails #{Rails.version} application starting in #{Rails.env} on #{url}" puts "=> Call with -d to detach" unless options[:daemonize] trap(:INT) { exit } puts "=> Ctrl-C to shutdown server" unless options[:daemonize] @@ -372,6 +383,15 @@ def start FileUtils.mkdir_p(Rails.root.join('tmp', dir_to_make)) end + unless options[:daemonize] + wrapped_app # touch the app so the logger is set up + + console = ActiveSupport::Logger.new($stdout) + console.formatter = Rails.logger.formatter + + Rails.logger.extend(ActiveSupport::Logger.broadcast(console)) + end + super ensure # The '-h' option calls exit before @options is set. @@ -380,10 +400,18 @@ ensure end </ruby> -This is where the first output of the Rails initialization happens. This method creates a trap for +INT+ signals, so if you +CTRL+C+ the server, it will exit the process. As we can see from the code here, it will create the +tmp/cache+, +tmp/pids+, +tmp/sessions+ and +tmp/sockets+ directories if they don't already exist prior to calling +super+. The +super+ method will call +Rack::Server.start+ which begins its definition like this: +This is where the first output of the Rails initialization happens. This +method creates a trap for +INT+ signals, so if you +CTRL-C+ the server, +it will exit the process. As we can see from the code here, it will +create the +tmp/cache+, +tmp/pids+, +tmp/sessions+ and +tmp/sockets+ +directories. It then calls +wrapped_app+ which is responsible for +creating the Rack app, before creating and assignig an +instance of +ActiveSupport::Logger+. + +The +super+ method will call +Rack::Server.start+ which begins its definition like this: <ruby> -def start +def start &blk if options[:warn] $-w = true end @@ -403,22 +431,37 @@ def start pp wrapped_app pp app end -end -</ruby> -In a Rails application, these options are not set at all and therefore aren't used at all. The first line of code that's executed in this method is a call to this method: + check_pid! if options[:pid] -<ruby> -wrapped_app + # Touch the wrapped app, so that the config.ru is loaded before + # daemonization (i.e. before chdir, etc). + wrapped_app + + daemonize_app if options[:daemonize] + + write_pid if options[:pid] + + trap(:INT) do + if server.respond_to?(:shutdown) + server.shutdown + else + exit + end + end + + server.run wrapped_app, options, &blk +end </ruby> -This method calls another method: +The interesting part for a Rails app is the last line, +server.run+. Here we encounter the +wrapped_app+ method again, which this time +we're going to explore more. <ruby> @wrapped_app ||= build_app app </ruby> -Then the +app+ method here is defined like so: +The +app+ method here is defined like so: <ruby> def app @@ -440,7 +483,7 @@ The +options[:config]+ value defaults to +config.ru+ which contains this: # This file is used by Rack-based servers to start the application. require ::File.expand_path('../config/environment', __FILE__) -run YourApp::Application +run <%= app_const %> </ruby> @@ -489,6 +532,7 @@ require "rails" action_controller action_mailer rails/test_unit + sprockets/rails ).each do |framework| begin require "#{framework}/railtie" @@ -501,13 +545,19 @@ First off the line is the +rails+ require itself. h4. +railties/lib/rails.rb+ -This file is responsible for the initial definition of the +Rails+ module and, rather than defining the autoloads like +ActiveSupport+, +ActionDispatch+ and so on, it actually defines other functionality. Such as the +root+, +env+ and +application+ methods which are extremely useful in Rails 3 applications. +This file is responsible for the initial definition of the +Rails+ +module and, rather than defining the autoloads like +ActiveSupport+, ++ActionDispatch+ and so on, it actually defines other functionality. +Such as the +root+, +env+ and +application+ methods which are extremely +useful in Rails 4 applications. However, before all that takes place the +rails/ruby_version_check+ file is required first. h4. +railties/lib/rails/ruby_version_check.rb+ -This file simply checks if the Ruby version is less than 1.8.7 or is 1.9.1 and raises an error if that is the case. Rails 3 simply will not run on earlier versions of Ruby than 1.8.7 or 1.9.1. +This file simply checks if the Ruby version is less than 1.9.3 and +raises an error if that is the case. Rails 4 simply will not run on +earlier versions of Ruby. NOTE: You should always endeavor to run the latest version of Ruby with your Rails applications. The benefits are many, including security fixes and the like, and very often there is a speed increase associated with it. The caveat is that you could have code that potentially breaks on the latest version, which should be fixed to work on the latest version rather than kept around as an excuse not to upgrade. @@ -523,35 +573,28 @@ end These methods can be used to silence STDERR responses and the +silence_stream+ allows you to also silence other streams. Additionally, this mixin allows you to suppress exceptions and capture streams. For more information see the "Silencing Warnings, Streams, and Exceptions":active_support_core_extensions.html#silencing-warnings-streams-and-exceptions section from the Active Support Core Extensions Guide. -h4. +active_support/core_ext/logger.rb+ - -The next file that is required is another Active Support core extension, this time to the +Logger+ class. This begins by defining the +around_[level]+ helpers for the +Logger+ class as well as other methods such as a +datetime_format+ getter and setter for the +formatter+ object tied to a +Logger+ object. +h4. +active_support/core_ext/array/extract_options.rb+ -For more information see the "Extensions to Logger":active_support_core_extensions.html#extensions-to-logger section from the Active Support Core Extensions Guide. +The next file that is required is another Active Support core extension, +this time to the +Array+ and +Hash+ classes. This file defines an ++extract_options!+ method which Rails uses to extract options from +parameters. h4. +railties/lib/rails/application.rb+ -The next file required by +railties/lib/rails.rb+ is +application.rb+. This file defines the +Rails::Application+ constant which the application's class defined in +config/application.rb+ in a standard Rails application depends on. Before the +Rails::Application+ class is defined however, there's some other files that get required first. - -The first of these is +active_support/core_ext/hash/reverse_merge+ which can be "read about in the Active Support Core Extensions guide":active_support_core_extensions.html#merging under the "Merging" section. - -h4. +active_support/file_update_checker.rb+ - -The +ActiveSupport::FileUpdateChecker+ class defined within this file is responsible for checking if a file has been updated since it was last checked. This is used for monitoring the routes file for changes during development environment runs. +The next file required by +railties/lib/rails.rb+ is +application.rb+. +This file defines the +Rails::Application+ constant which the +application's class defined in +config/application.rb+ in a standard +Rails application depends on. -h4. +railties/lib/rails/plugin.rb+ +Before the +Rails::Application+ class is +defined however, +rails/engine+ is also loaded, which is responsible for +handling the behavior and definitions of Rails engines. -This file defines +Rails::Plugin+ which inherits from +Rails::Engine+. Unlike +Rails::Engine+ and +Rails::Railtie+ however, this class is not designed to be inherited from. Instead, this is used simply for loading plugins from within an application and an engine. +TIP: You can read more about engines in the "Getting Started with Engines":engines.html guide. -This file begins by requiring +rails/engine.rb+ - -h4. +railties/lib/rails/engine.rb+ - -The +rails/engine.rb+ file defines the +Rails::Engine+ class which inherits from +Rails::Railtie+. The +Rails::Engine+ class defines much of the functionality found within a standard application class such as the +routes+ and +config+ methods. - -The "API documentation":http://api.rubyonrails.org/classes/Rails/Engine.html for +Rails::Engine+ explains the function of this class pretty well. - -This file's first line requires +rails/railtie.rb+. +Among other things, Rails Engine is also responsible for loading the +Railtie class. h4. +railties/lib/rails/railtie.rb+ @@ -613,7 +656,7 @@ h4. +activesupport/lib/active_support/deprecation/proxy_wrappers.rb+ +proxy_wrappers.rb+ defines deprecation wrappers for methods, instance variables and constants. Previously, this was used for the +RAILS_ENV+ and +RAILS_ROOT+ constants for 3.0 but since then these constants have been removed. The deprecation message that would be raised from these would be something like: <plain> - BadConstant is deprecated! Use GoodConstant instead. +BadConstant is deprecated! Use GoodConstant instead. </plain> h4. +active_support/ordered_options+ @@ -622,7 +665,30 @@ This file is the next file required from +rails/configuration.rb+ is the file th The next file required is +active_support/core_ext/hash/deep_dup+ which is covered in "Active Support Core Extensions guide":active_support_core_extensions.html#deep_dup -The file that is required next from is +rails/paths+ +h4. +active_support/core_ext/object+ + +This file is responsible for requiring many more Active Support core extensions: + +<ruby> +require 'active_support/core_ext/object/acts_like' +require 'active_support/core_ext/object/blank' +require 'active_support/core_ext/object/duplicable' +require 'active_support/core_ext/object/deep_dup' +require 'active_support/core_ext/object/try' +require 'active_support/core_ext/object/inclusion' + +require 'active_support/core_ext/object/conversions' +require 'active_support/core_ext/object/instance_variables' + +require 'active_support/core_ext/object/to_json' +require 'active_support/core_ext/object/to_param' +require 'active_support/core_ext/object/to_query' +require 'active_support/core_ext/object/with_options' +</ruby> + +The Rails API documentation covers them in great detail, so we're not going to explain each of them. + +The file that is required next from +rails/configuration+ is +rails/paths+. h4. +railties/lib/rails/paths.rb+ @@ -638,7 +704,6 @@ module Rails autoload :Debugger, "rails/rack/debugger" autoload :Logger, "rails/rack/logger" autoload :LogTailer, "rails/rack/log_tailer" - autoload :Static, "rails/rack/static" end end </ruby> @@ -664,9 +729,23 @@ h4. +active_support/inflections+ 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". +<ruby> +inflect.irregular('zombie', 'zombies') +</ruby> + h4. +activesupport/lib/active_support/inflector/transliterate.rb+ -In this file is where the "+transliterate+":http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-transliterate and +parameterize+:http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-parameterize methods are defined. The documentation for both of these methods is very much worth reading. +This is the file that defines the "+transliterate+":http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-transliterate and "+parameterize+":http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-parameterize methods. + +h4. +active_support/core_ext/module/introspection+ + +The next file loaded by +rails/railtie+ is the introspection core +extension, which extends +Module+ with methods like +parent_name+, +parent+ and ++parents+. + +h4. +active_support/core_ext/module/delegation+ + +The final file loaded by +rails/railtie+ is the delegation core extension, which defines the "+delegate+":http://api.rubyonrails.org/classes/Module.html#method-i-delegate method. h4. Back to +railties/lib/rails/railtie.rb+ @@ -846,7 +925,7 @@ The +initializers_chain+ method referenced in the +initializers_for+ method is d <ruby> def initializers_chain initializers = Collection.new - ancestors.reverse_each do | klass | + ancestors.reverse_each do |klass| next unless klass.respond_to?(:initializers) initializers = initializers + klass.initializers end @@ -909,46 +988,35 @@ This file defines the +ActiveSupport::Railtie+ constant which like the +I18n::Ra Then this Railtie sets up three more initializers: -* +active_support.initialize_whiny_nils+ * +active_support.deprecation_behavior+ * +active_support.initialize_time_zone+ +* +active_support.set_configs+ We will cover what each of these initializers do when they run. Once the +active_support/railtie+ file has finished loading the next file required from +railties/lib/rails.rb+ is the +action_dispatch/railtie+. -h4. +activesupport/lib/action_dispatch/railtie.rb+ +h4. +actionpack/lib/action_dispatch/railtie.rb+ This file defines the +ActionDispatch::Railtie+ class, but not before requiring +action_dispatch+. -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. - -<ruby> -activesupport_path = File.expand_path('../../../activesupport/lib', __FILE__) -$:.unshift(activesupport_path) if File.directory?(activesupport_path) && !$:.include?(activesupport_path) - -activemodel_path = File.expand_path('../../../activemodel/lib', __FILE__) -$:.unshift(activemodel_path) if File.directory?(activemodel_path) && !$:.include?(activemodel_path) -</ruby> - -In effect, these lines only define the +activesupport_path+ and +activemodel_path+ variables and nothing more. +h4. +actionpack/lib/action_dispatch.rb+ -The next two requires in this file are already done, so they are not run: +This file starts off with the following requires: <ruby> require 'active_support' require 'active_support/dependencies/autoload' +require 'active_support/core_ext/module/attribute_accessors' </ruby> -The following require is to +action_pack+ (+activesupport/lib/action_pack.rb+) which has a 22-line copyright notice at the top of it and ends in a simple require to +action_pack/version+. This file, like other +version.rb+ files before it, defines the +ActionPack::VERSION+ constant: +The following require is to +action_pack+ (+actionpack/lib/action_pack.rb+) which contains a simple require to +action_pack/version+. This file, like other +version.rb+ files before it, defines the +ActionPack::VERSION+ constant: <ruby> module ActionPack module VERSION #:nodoc: - MAJOR = 3 - MINOR = 1 + MAJOR = 4 + MINOR = 0 TINY = 0 PRE = "beta" @@ -966,8 +1034,8 @@ This file makes a require to +active_model/version+ which defines the version fo <ruby> module ActiveModel module VERSION #:nodoc: - MAJOR = 3 - MINOR = 1 + MAJOR = 4 + MINOR = 0 TINY = 0 PRE = "beta" @@ -1004,7 +1072,7 @@ Once it has finished loading, the +I18n.load_path+ method is used to add the +ac The loading of this file finishes the loading of +active_model+ and so we go back to +action_dispatch+. -h4. Back to +activesupport/lib/action_dispatch.rb+ +h4. Back to +actionpack/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: @@ -1018,7 +1086,7 @@ The +Assertions+ module is in the +action_dispatch/testing+ folder rather than s Finally, this file defines a top-level autoload, the +Mime+ constant. -h4. Back to +activesupport/lib/action_dispatch/railtie.rb+ +h4. Back to +actionpack/lib/action_dispatch/railtie.rb+ After +action_dispatch+ is required in this file, the +ActionDispatch::Railtie+ class is defined and is yet another class that inherits from +Rails::Railtie+. This class defines some initial configuration option defaults for +config.action_dispatch+ before setting up a single initializer called +action_dispatch.configure+. @@ -1040,22 +1108,21 @@ h4. +activerecord/lib/active_record.rb+ This file begins by detecting if the +lib+ directories of +active_support+ and +active_model+ are not in the load path and if they aren't then adds them. As we saw back in +action_dispatch.rb+, these directories are already there. -The first three requires have already been done by other files and so aren't loaded here, but the 4th require, the one to +arel+ will require the file provided by the Arel gem, which defines the +Arel+ module. +The first couple of requires have already been done by other files and so aren't loaded here, but the next one to +arel+ will require the file provided by the Arel gem, which defines the +Arel+ module. <ruby> require 'active_support' -require 'active_support/i18n' require 'active_model' require 'arel' </ruby> -The 5th require in this file is one to +active_record/version+ which defines the +ActiveRecord::VERSION+ constant: +The file required next is +active_record/version+ which defines the +ActiveRecord::VERSION+ constant: <ruby> module ActiveRecord module VERSION #:nodoc: - MAJOR = 3 - MINOR = 1 + MAJOR = 4 + MINOR = 0 TINY = 0 PRE = "beta" @@ -1079,7 +1146,9 @@ This will set the engine for +Arel::Table+ to be +ActiveRecord::Base+. The file then finishes with this line: <ruby> -I18n.load_path << File.dirname(__FILE__) + '/active_record/locale/en.yml' +ActiveSupport.on_load(:i18n) do + I18n.load_path << File.dirname(__FILE__) + '/active_record/locale/en.yml' +end </ruby> This will add the translations from +activerecord/lib/active_record/locale/en.yml+ to the load path for +I18n+, with this file being parsed when all the translations are loaded. diff --git a/guides/source/layouts_and_rendering.textile b/guides/source/layouts_and_rendering.textile index e4a1fd6951..b0a87a5981 100644 --- a/guides/source/layouts_and_rendering.textile +++ b/guides/source/layouts_and_rendering.textile @@ -860,12 +860,6 @@ You can supply a hash of additional HTML options: <%= image_tag "icons/delete.gif", {:height => 45} %> </erb> -You can also supply an alternate image to show on mouseover: - -<erb> -<%= image_tag "home.gif", :onmouseover => "menu/home_highlight.gif" %> -</erb> - You can supply alternate text for the image which will be used if the user has images turned off in their browser. If you do not specify an alt text explicitly, it defaults to the file name of the file, capitalized and with no extension. For example, these two image tags would return the same code: <erb> diff --git a/guides/source/migrations.textile b/guides/source/migrations.textile index f855072fd8..52dba76e68 100644 --- a/guides/source/migrations.textile +++ b/guides/source/migrations.textile @@ -737,9 +737,7 @@ column. class AddFlagToProduct < ActiveRecord::Migration def change add_column :products, :flag, :boolean - Product.all.each do |product| - product.update_attributes!(:flag => false) - end + Product.update_all :flag => false end end </ruby> @@ -762,9 +760,7 @@ column. class AddFuzzToProduct < ActiveRecord::Migration def change add_column :products, :fuzz, :string - Product.all.each do |product| - product.update_attributes! :fuzz => 'fuzzy' - end + Product.update_all :fuzz => 'fuzzy' end end </ruby> @@ -816,9 +812,7 @@ class AddFlagToProduct < ActiveRecord::Migration def change add_column :products, :flag, :boolean Product.reset_column_information - Product.all.each do |product| - product.update_attributes!(:flag => false) - end + Product.update_all :flag => false end end </ruby> @@ -833,9 +827,7 @@ class AddFuzzToProduct < ActiveRecord::Migration def change add_column :products, :fuzz, :string Product.reset_column_information - Product.all.each do |product| - product.update_attributes!(:fuzz => 'fuzzy') - end + Product.update_all :fuzz => 'fuzzy' end end </ruby> diff --git a/guides/source/rails_on_rack.textile b/guides/source/rails_on_rack.textile index ff862273fd..3a7c392508 100644 --- a/guides/source/rails_on_rack.textile +++ b/guides/source/rails_on_rack.textile @@ -23,29 +23,49 @@ h3. Rails on Rack h4. Rails Application's Rack Object -<tt>ActionController::Dispatcher.new</tt> is the primary Rack application object of a Rails application. Any Rack compliant web server should be using +ActionController::Dispatcher.new+ object to serve a Rails application. +<tt>ApplicationName::Application</tt> is the primary Rack application object of a Rails application. Any Rack compliant web server should be using +ApplicationName::Application+ object to serve a Rails application. h4. +rails server+ -<tt>rails server</tt> does the basic job of creating a +Rack::Builder+ object and starting the webserver. This is Rails' equivalent of Rack's +rackup+ script. +<tt>rails server</tt> does the basic job of creating a +Rack::Server+ object and starting the webserver. -Here's how +rails server+ creates an instance of +Rack::Builder+ +Here's how +rails server+ creates an instance of +Rack::Server+ <ruby> -app = Rack::Builder.new { - use Rails::Rack::LogTailer unless options[:detach] - use Rails::Rack::Debugger if options[:debugger] - use ActionDispatch::Static - run ActionController::Dispatcher.new -}.to_app +Rails::Server.new.tap { |server| + require APP_PATH + Dir.chdir(Rails.application.root) + server.start +} </ruby> -Middlewares used in the code above are primarily useful only in the development environment. The following table explains their usage: +The +Rails::Server+ inherits from +Rack::Server+ and calls the +Rack::Server#start+ method this way: + +<ruby> +class Server < ::Rack::Server + def start + ... + super + end +end +</ruby> + +Here's how it loads the middlewares: + +<ruby> +def middleware + middlewares = [] + middlewares << [Rails::Rack::Debugger] if options[:debugger] + middlewares << [::Rack::ContentLength] + Hash.new(middlewares) +end +</ruby> + ++Rails::Rack::Debugger+ is primarily useful only in the development environment. The following table explains the usage of the loaded middlewares: |_.Middleware|_.Purpose| -|+Rails::Rack::LogTailer+|Appends log file output to console| -|+ActionDispatch::Static+|Serves static files inside +Rails.root/public+ directory| |+Rails::Rack::Debugger+|Starts Debugger| +|+Rack::ContentLength+|Counts the number of bytes in the response and set the HTTP Content-Length header| h4. +rackup+ @@ -55,9 +75,9 @@ To use +rackup+ instead of Rails' +rails server+, you can put the following insi # Rails.root/config.ru require "config/environment" -use Rails::Rack::LogTailer -use ActionDispatch::Static -run ActionController::Dispatcher.new +use Rack::Debugger +use Rack::ContentLength +run ApplicationName::Application </ruby> And start the server: @@ -72,11 +92,11 @@ To find out more about different +rackup+ options: $ rackup --help </shell> -h3. Action Controller Middleware Stack +h3. Action Dispatcher Middleware Stack -Many of Action Controller's internal components are implemented as Rack middlewares. +ActionController::Dispatcher+ uses +ActionController::MiddlewareStack+ to combine various internal and external middlewares to form a complete Rails Rack application. +Many of Action Dispatchers's internal components are implemented as Rack middlewares. +Rails::Application+ uses +ActionDispatch::MiddlewareStack+ to combine various internal and external middlewares to form a complete Rails Rack application. -NOTE: +ActionController::MiddlewareStack+ is Rails' equivalent of +Rack::Builder+, but built for better flexibility and more features to meet Rails' requirements. +NOTE: +ActionDispatch::MiddlewareStack+ is Rails' equivalent of +Rack::Builder+, but built for better flexibility and more features to meet Rails' requirements. h4. Inspecting Middleware Stack @@ -111,7 +131,7 @@ use ActionDispatch::Head use Rack::ConditionalGet use Rack::ETag use ActionDispatch::BestStandardsSupport -run Blog::Application.routes +run ApplicationName::Application.routes </ruby> Purpose of each of this middlewares is explained in the "Internal Middlewares":#internal-middleware-stack section. @@ -152,9 +172,9 @@ You can swap an existing middleware in the middleware stack using +config.middle config.middleware.swap ActionDispatch::ShowExceptions, Lifo::ShowExceptions </ruby> -h5. Middleware Stack is an Array +h5. Middleware Stack is an Enumerable -The middleware stack behaves just like a normal +Array+. You can use any +Array+ methods to insert, reorder, or remove items from the stack. Methods described in the section above are just convenience methods. +The middleware stack behaves just like a normal +Enumerable+. You can use any +Enumerable+ methods to manipulate or interrogate the stack. The middleware stack also implements some +Array+ methods including <tt>[]</tt>, +unshift+ and +delete+. Methods described in the section above are just convenience methods. Append following lines to your application configuration: @@ -172,7 +192,7 @@ use ActionDispatch::Static use #<ActiveSupport::Cache::Strategy::LocalCache::Middleware:0x00000001c304c8> use Rack::Runtime ... -run Myapp::Application.routes +run Blog::Application.routes </shell> h4. Internal Middleware Stack @@ -264,7 +284,7 @@ config.middleware.clear <ruby> # config.ru use MyOwnStackFromScratch -run ActionController::Dispatcher.new +run ApplicationName::Application </ruby> h3. Resources diff --git a/guides/source/routing.textile b/guides/source/routing.textile index 4a50edbb15..0773a96c67 100644 --- a/guides/source/routing.textile +++ b/guides/source/routing.textile @@ -395,7 +395,7 @@ NOTE: You can't use +:namespace+ or +:module+ with a +:controller+ path segment. get ':controller(/:action(/:id))', :controller => /admin\/[^\/]+/ </ruby> -TIP: By default dynamic segments don't accept dots - this is because the dot is used as a separator for formatted routes. If you need to use a dot within a dynamic segment add a constraint which overrides this - for example +:id+ => /[^\/]+/ allows anything except a slash. +TIP: By default dynamic segments don't accept dots - this is because the dot is used as a separator for formatted routes. If you need to use a dot within a dynamic segment, add a constraint that overrides this – for example, +:id+ => /[^\/]+/ allows anything except a slash. h4. Static Segments @@ -445,6 +445,14 @@ get 'exit' => 'sessions#destroy', :as => :logout This will create +logout_path+ and +logout_url+ as named helpers in your application. Calling +logout_path+ will return +/exit+ +You can also use this to override routing methods defined by resources, like this: + +<ruby> +get ':username', :to => "users#show", :as => :user +</ruby> + +This will define a +user_path+ method that will be available in controllers, helpers and views that will go to a route such as +/bob+. Inside the +show+ action of +UsersController+, +params[:username]+ will contain the username for the user. Change +:username+ in the route definition if you do not want your parameter name to be +:username+. + h4. HTTP Verb Constraints In general, you should use the +get+, +post+, +put+ and +delete+ methods to constrain a route to a particular verb. You can use the +match+ method with the +:via+ option to match multiple verbs at once: diff --git a/guides/source/ruby_on_rails_guides_guidelines.textile b/guides/source/ruby_on_rails_guides_guidelines.textile index f3e934d38c..dd209b61d6 100644 --- a/guides/source/ruby_on_rails_guides_guidelines.textile +++ b/guides/source/ruby_on_rails_guides_guidelines.textile @@ -47,7 +47,13 @@ h4. Generation To generate all the guides, just +cd+ into the *+guides+* directory and execute: <plain> -bundle exec rake generate_guides +bundle exec rake guides:generate +</plain> + +or + +<plain> +bundle exec rake guides:generate:html </plain> (You may need to run +bundle install+ first to install the required gems.) @@ -56,7 +62,7 @@ To process +my_guide.textile+ and nothing else use the +ONLY+ environment variab <plain> touch my_guide.textile -bundle exec rake generate_guides ONLY=my_guide +bundle exec rake guides:generate ONLY=my_guide </plain> By default, guides that have not been modified are not processed, so +ONLY+ is rarely needed in practice. @@ -68,7 +74,13 @@ It is also recommended that you work with +WARNINGS=1+. This detects duplicate I If you want to generate guides in a language other than English, you can keep them in a separate directory under +source+ (eg. <tt>source/es</tt>) and use the +GUIDES_LANGUAGE+ environment variable: <plain> -bundle exec rake generate_guides GUIDES_LANGUAGE=es +bundle exec rake guides:generate GUIDES_LANGUAGE=es +</plain> + +If you want to see all the environment variables you can use to configure the generation script just run: + +<plain> +rake </plain> h4. Validation @@ -76,7 +88,7 @@ h4. Validation Please validate the generated HTML with: <plain> -bundle exec rake validate_guides +bundle exec rake guides:validate </plain> Particularly, titles get an ID generated from their content and this often leads to duplicates. Please set +WARNINGS=1+ when generating guides to detect them. The warning messages suggest a solution. @@ -85,8 +97,8 @@ h3. Kindle Guides h4(#generation-kindle). Generation -To generate guides for the Kindle, you need to provide +KINDLE=1+ as an environment variable: +To generate guides for the Kindle, use the following rake task: <plain> -KINDLE=1 bundle exec rake generate_guides +bundle exec rake guides:generate:kindle </plain> diff --git a/guides/source/security.textile b/guides/source/security.textile index ac55d60368..cc0894fc77 100644 --- a/guides/source/security.textile +++ b/guides/source/security.textile @@ -236,6 +236,17 @@ protect_from_forgery :secret => "123456789012345678901234567890..." This will automatically include a security token, calculated from the current session and the server-side secret, in all forms and Ajax requests generated by Rails. You won't need the secret, if you use CookieStorage as session storage. If the security token doesn't match what was expected, the session will be reset. *Note:* In Rails versions prior to 3.0.4, this raised an <tt>ActionController::InvalidAuthenticityToken</tt> error. +It is common to use persistent cookies to store user information, with +cookies.permanent+ for example. In this case, the cookies will not be cleared and the out of the box CSRF protection will not be effective. If you are using a different cookie store than the session for this information, you must handle what to do with it yourself: + +<ruby> +def handle_unverified_request + super + sign_out_user # Example method that will destroy the user cookies. +end +</ruby> + +The above method can be placed in the +ApplicationController+ and will be called when a CSRF token is not present on a non-GET request. + Note that _(highlight)cross-site scripting (XSS) vulnerabilities bypass all CSRF protections_. XSS gives the attacker access to all elements on a page, so he can read the CSRF security token from a form or directly submit the form. Read <a href="#cross-site-scripting-xss">more about XSS</a> later. h3. Redirection and Files diff --git a/guides/source/upgrading_ruby_on_rails.textile b/guides/source/upgrading_ruby_on_rails.textile index 2b2e65c813..6cdc6ab289 100644 --- a/guides/source/upgrading_ruby_on_rails.textile +++ b/guides/source/upgrading_ruby_on_rails.textile @@ -34,13 +34,25 @@ h4(#plugins4_0). vendor/plugins Rails 4.0 no longer supports loading plugins from <tt>vendor/plugins</tt>. You must replace any plugins by extracting them to gems and adding them to your Gemfile. If you choose not to make them gems, you can move them into, say, <tt>lib/my_plugin/*</tt> and add an appropriate initializer in <tt>config/initializers/my_plugin.rb</tt>. -h4(#identity_map4_0). IdentityMap +h4(#identity_map4_0). Identity Map -Rails 4.0 has removed <tt>IdentityMap</tt> from <tt>ActiveRecord</tt>, due to "some inconsistencies with associations":https://github.com/rails/rails/commit/302c912bf6bcd0fa200d964ec2dc4a44abe328a6. If you have manually enabled it in your application, you will have to remove the following config that has no effect anymore: <tt>config.active_record.identity_map</tt>. +Rails 4.0 has removed the identity map from Active Record, due to "some inconsistencies with associations":https://github.com/rails/rails/commit/302c912bf6bcd0fa200d964ec2dc4a44abe328a6. If you have manually enabled it in your application, you will have to remove the following config that has no effect anymore: <tt>config.active_record.identity_map</tt>. -h4(#active_model4_0). ActiveModel +h4(#active_record4_0). Active Record -Rails 4.0 has changed how errors attach with the ConfirmationValidator. Now when confirmation validations fail the error will be attached to <tt>:#{attribute}_confirmation</tt> instead of <tt>attribute</tt>. +The <tt>delete</tt> method in collection associations can now receive <tt>Fixnum</tt> or <tt>String</tt> arguments as record ids, besides records, pretty much like the <tt>destroy</tt> method does. Previously it raised <tt>ActiveRecord::AssociationTypeMismatch</tt> for such arguments. From Rails 4.0 on <tt>delete</tt> automatically tries to find the records matching the given ids before deleting them. + +h4(#active_model4_0). Active Model + +Rails 4.0 has changed how errors attach with the <tt>ActiveModel::Validations::ConfirmationValidator</tt>. Now when confirmation validations fail the error will be attached to <tt>:#{attribute}_confirmation</tt> instead of <tt>attribute</tt>. + +h4(#action_pack4_0). Action Pack + +Rails 4.0 changed how <tt>assert_generates</tt>, <tt>assert_recognizes</tt>, and <tt>assert_routing</tt> work. Now all these assertions raise <tt>Assertion</tt> instead of <tt>ActionController::RoutingError</tt>. + +h4(#helpers_order). Helpers Loading Order + +The loading order of helpers from more than one directory has changed in Rails 4.0. Previously, helpers from all directories were gathered and then sorted alphabetically. After upgrade to Rails 4.0 helpers will preserve the order of loaded directories and will be sorted alphabetically only within each directory. Unless you explicitly use <tt>helpers_path</tt> parameter, this change will only impact the way of loading helpers from engines. If you rely on the fact that particular helper from engine loads before or after another helper from application or another engine, you should check if correct methods are available after upgrade. If you would like to change order in which engines are loaded, you can use <tt>config.railties_order=</tt> method. h3. Upgrading from Rails 3.1 to Rails 3.2 |